# Run a tool or a program

The one execution primitive: a single tool call and a code program are the same operation, with one id space, one status machine, and one resume. A run that fails answers 200 with the failure embedded — the request succeeded, the run did not. Retrying with the same `idempotencyKey` returns the original run and answers 200 instead of 201.

## POST `/v1/connectors/runs`

### Authorization

`Authorization` Bearer token · header required

`Authorization: Bearer <token>` with an API key (`sfa_` prefix), an OAuth access token, a session token, or a Space machine credential (`sfm_` prefix).

or

`Authorization` OAuth2 access token · header required

OAuth 2.0 with Spacefast scopes. People use the authorization code flow; machines use client credentials.

**Scopes:** `connectors:execute`

### Query parameters

`team` string

min length 1 · max length 255

### Request body

required `application/json`

`input` object required

One call, or a program that makes many. Same endpoint either way.

#### Show properties

One of:

- object

`kind` string required

`address` string required

`<connectionId>/<tool>`, straight off a tool listing.

min length 1 · max length 512

`args` object

Arguments, validated against the tool's own input schema.

default: {}

- object

`kind` string required

`code` string required

A program run in the sandbox. It may call any tool the calling credential is granted.

min length 1 · max length 200000

`waitMs` integer

How long to hold the request waiting for a terminal status before answering `running`.

min 0 · max 120000

`idempotencyKey` string

Retry with the same key to get the original run back (200, not 201) instead of running it twice.

min length 1 · max length 320

`unattendedApprovals` string

What to do when a call needs approval and nobody is watching: park it for a person, or fail fast.

default: "park"

Allowed: `park`, `deny`

### Responses

#### 200 Response for status 200

`$schema` string <uri>

Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.

`data` object required

One execution. A tool call and a code program are the same resource.

#### Show properties

One of:

- object

`id` string required

Run id (`cxr_`).

`input` object required

What the run was asked to do, without echoing arguments that may carry customer data.

##### Show properties

`kind` string required

`tool` is one call; `code` is a program that may make many. Same endpoint, same id space, same resume.

Allowed: `tool`, `code`

`address` string | any required

Tool address for a `tool` run; null for a `code` program.

Any of:

- string

`digest` string required

Content digest of the submitted input, so a retry can be recognized without replaying it.

`usage` object required

What this run has spent. Budgets are enforced against these numbers.

##### Show properties

`toolCalls` integer required

Tool calls made so far.

min -9007199254740991 · max 9007199254740991

`egressBytes` integer required

Bytes read from third-party APIs so far.

min -9007199254740991 · max 9007199254740991

`durationMs` integer required

Wall-clock time spent executing so far.

min -9007199254740991 · max 9007199254740991

`createdAt` string <date-time> required

matches ^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$

`status` string required

Still executing. Poll the run, or submit the next one with a longer `waitMs`.

object

`id` string required

Run id (`cxr_`).

`input` object required

What the run was asked to do, without echoing arguments that may carry customer data.

##### Show properties

`kind` string required

`tool` is one call; `code` is a program that may make many. Same endpoint, same id space, same resume.

Allowed: `tool`, `code`

`address` string | any required

Tool address for a `tool` run; null for a `code` program.

Any of:

- string

`digest` string required

Content digest of the submitted input, so a retry can be recognized without replaying it.

`usage` object required

What this run has spent. Budgets are enforced against these numbers.

##### Show properties

`toolCalls` integer required

Tool calls made so far.

min -9007199254740991 · max 9007199254740991

`egressBytes` integer required

Bytes read from third-party APIs so far.

min -9007199254740991 · max 9007199254740991

`durationMs` integer required

Wall-clock time spent executing so far.

min -9007199254740991 · max 9007199254740991

`createdAt` string <date-time> required

`status` string required

`completedAt` string <date-time> required

`result` any required

Whatever the tool or program returned.

object

`id` string required

Run id (`cxr_`).

`input` object required

What the run was asked to do, without echoing arguments that may carry customer data.

##### Show properties

`kind` string required

`tool` is one call; `code` is a program that may make many. Same endpoint, same id space, same resume.

Allowed: `tool`, `code`

`address` string | any required

Tool address for a `tool` run; null for a `code` program.

Any of:

- string

`digest` string required

Content digest of the submitted input, so a retry can be recognized without replaying it.

`usage` object required

What this run has spent. Budgets are enforced against these numbers.

##### Show properties

`toolCalls` integer required

Tool calls made so far.

min -9007199254740991 · max 9007199254740991

`egressBytes` integer required

Bytes read from third-party APIs so far.

min -9007199254740991 · max 9007199254740991

`durationMs` integer required

Wall-clock time spent executing so far.

min -9007199254740991 · max 9007199254740991

`createdAt` string <date-time> required

`status` string required

`completedAt` string <date-time> required

default Problem details (RFC 9457). Any 4xx/5xx response is one `application/problem+json` document.

#### `$schema` string <uri>

Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.

`type` string required

URL of the documentation page for this error. Derived from `code`.

`title` string required

Human-readable name of the error type. Derived from `code`.

`status` integer required

HTTP status of the response, repeated in the body.

min -9007199254740991 · max 9007199254740991

`detail` string required

What went wrong in this request.

`code` string required

Stable snake_case error code. Match on this, not on `detail`.

`pointer` string

RFC 6901 JSON Pointer to the request field or batch entry that failed, for example `/files/37/path`. Present on validation failures.

`details` object

Machine-readable context keyed by the error code.

`suggestions` string[]

Recovery steps safe to show to a person.

`next` string[]

Commands or API requests to run next, usable as written.

`requestId` string required

ID of this request, from the `X-Request-Id` header or generated. Quote it when contacting support.

## Try it

### Server

Base URL `https://api.spacefast.com`

Custom base URL

Overrides the selected server when set.

### Authorization

Bearer token

Remember on this device

Include my values in samples

### Parameters

`team` query

### Body

application/json

`input` string* One call, or a program that makes many. Same endpoint either way.

`waitMs` integer How long to hold the request waiting for a terminal status before answering `running`.

`idempotencyKey` string Retry with the same key to get the original run back (200, not 201) instead of running it twice.

`unattendedApprovals` string — park deny What to do when a call needs approval and nobody is watching: park it for a person or fail fast.