Skip to main content
POST
JavaScript

Authorizations

Authorization
string
header
required

Enter your API key as the bearer token. Set header: Authorization to Bearer <api_key>

Body

application/json
connector_id
string
required

ID of the connector to execute.

arguments
object

Arguments to pass to the connector. Optional if the connector does not require any arguments.

secret_bindings
object

Mapping of secret slot names to the IDs of saved, user-owned secrets. Each of the connector's required_secrets must appear here or in secret_values, but not both.

secret_values
object

Mapping of secret slot names to secret values supplied directly for this run, instead of referencing a saved secret. Use a login shape ({username, password, totp_secret?}) for login slots and a string shape ({value}) for string slots. Values are not persisted.

async
boolean
default:false

When true, return immediately with a pending run; poll retrieveRun for the result. Results above 1,000,000 UTF-8 JSON bytes are discarded and finish with result_too_large. Retry those requests with async=false to receive the result directly.

max_timeout_s
integer
default:300

Maximum execution time in seconds before the run is timed out.

Required range: 1 <= x <= 3600
proxy_settings
IspProxy · object

Proxy for the network traffic of this run. If you do not set it, a setting is automatically determined by the platform.

Response

Successful response

id
string
required

Unique identifier for the object.

connector_id
string
required

ID of the connector executed in this run.

connector_version
integer
required

Version of the connector executed in this run. Runs pin the version that was newest when they were created.

Example:

1

arguments
object
required

Arguments in this run for the connector's input parameters.

status
enum<string>
required

Lifecycle status of the run: pending, running, success, connector_error, timed_out, result_too_large, or internal_error. connector_error means the connector's code failed (see error); timed_out and internal_error are platform outcomes worth retrying; result_too_large means the result exceeded the execution limit or could not be retained for an async caller. Async results above 1 MB require a new synchronous request.

Available options:
pending,
running,
success,
connector_error,
timed_out,
result_too_large,
internal_error
result
object | null
required

Execution result of the run, matching the connector's output schema. Synchronous requests return successful results up to the 100 MB execution limit. Only results of at most 1,000,000 UTF-8 JSON bytes are stored. Larger results are returned once to the synchronous caller and are null on later retrieval. If delivery fails, the result cannot be retrieved later.

result_stored
boolean
required

Whether the result is retained for later retrieval.

result_size_bytes
integer | null
required

Size of the executor's serialized result in UTF-8 bytes, when known.

error
RunError · object | null
required

Why the run failed. Present iff status is connector_error; for platform failures the status itself is the reason.

has_logs
boolean
required

Whether the run has associated logs

created_at
string<date-time>
required

Timestamp when the object was created.

finished_at
string<date-time> | null
required

Timestamp when the object was last updated.

secret_bindings
object

Secrets to use for this run. This dict must be a mapping of secret slot names to secret IDs.