Skip to main content
POST
Run a read-only tool on a list of inputs
Business accounts only.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string

Repeat a request safely: the same key and body answer the first request's job again with Idempotent-Replayed: true; the same key with a different body answers idempotency_conflict. 1 to 200 letters, digits, _ or -, such as a UUID

Pattern: ^[A-Za-z0-9_-]{1,200}$

Body

application/json
tool_id
string
required

The ID of the read tool to run, from a tool search

Pattern: ^tool_[0-9a-f]{32}$
items
object[]

1 to 100 items, each its input and an optional key. Send items or inputs, not both

Required array length: 1 - 100 elements
inputs
object[]

1 to 100 inputs, for items without keys. Send items or inputs, not both

Required array length: 1 - 100 elements
defaults
object

Input fields every item shares; an item's own fields win

redact_at_rest
boolean

Staging and preview only: true seals what this job stores and redacts it once it settles, false keeps it readable, overriding the environment's setting. Production refuses a request that names it with invalid_request.

shape
string

Your saved shape of this tool, to get every item's result in that form; each item's job's shape says if it applied.

Example:

"shp_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190"

Response

The batch this Idempotency-Key already started, with Idempotent-Replayed: true

id
string
required

a batch ID: batch_ and 32 lowercase hex digits

Example:

"batch_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190"

type
enum<string>
required
Available options:
batch
status
enum<string>
required
Available options:
running,
completed,
cancelled
tool_id
string
required
counts
object
required
items
object[]
required
more_results
boolean
required

true when finished items' results were left out to keep this answer under 1 MiB: read the batch again for them

created_at
string
required

a string to be decoded into a Date

updated_at
string
required

a string to be decoded into a Date

completed_at
string | null
required

a string to be decoded into a Date