---
title: "Run a tool or a program"
method: POST
path: "/v1/connectors/runs"
tags: ["Connectors"]
---

# Run a tool or a program

`POST /v1/connectors/runs`

## Request

- Base URL: `https://api.spacefast.com`
- URL: `https://api.spacefast.com/v1/connectors/runs`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.spacefast.com/v1/auth/oauth2/authorize`, token URL `https://api.spacefast.com/v1/auth/oauth2/token`; client credentials, token URL `https://api.spacefast.com/v1/auth/oauth2/token`, scopes: `connectors:execute`)

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.

## Query parameters

- `team` string: Team id or slug to act for. Required only when the credential could act for more than one team.

## Request body

- object
  - `input` union, required: One call, or a program that makes many. Same endpoint either way.
    - object
      - `kind` 'tool', required
      - `address` string, required: `<connectionId>/<tool>`, straight off a tool listing.
      - `args` object: Arguments, validated against the tool's own input schema.
    - object
      - `kind` 'code', required
      - `code` string, required: A program run in the sandbox. It may call any tool the calling credential is granted.
  - `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` 'park' | 'deny': What to do when a call needs approval and nobody is watching: park it for a person, or fail fast.

## Response `200`

Response for status 200

- object
  - `$schema` string, uri: Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.
  - `data` union, required: One execution. A tool call and a code program are the same resource.
    - object
      - `origin` 'dashboard' | 'cli' | 'api' | 'mcp' | 'zero' | 'function' | 'system', required
      - `space` string, nullable, required: Space id that initiated this run, if any.
      - `handler` string, nullable, required: Runtime handler that initiated this run, if any.
      - `visitor` boolean, required: Whether a signed-in Space visitor initiated this run.
      - `id` string, required: Run id (`cxr_`).
      - `input` object, required: What the run was asked to do, without echoing arguments that may carry customer data.
        - `kind` 'tool' | 'code', required: `tool` is one call; `code` is a program that may make many. Same endpoint, same id space, same resume.
        - `address` string, nullable, required: Tool address for a `tool` run; null for a `code` program.
        - `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.
        - `toolCalls` integer, required: Tool calls made so far.
        - `egressBytes` integer, required: Bytes read from third-party APIs so far.
        - `durationMs` integer, required: Wall-clock time spent executing so far.
      - `createdAt` string, date-time, required
      - `status` 'running', required: Still executing. Poll the run, or submit the next one with a longer `waitMs`.
    - object
      - `origin` 'dashboard' | 'cli' | 'api' | 'mcp' | 'zero' | 'function' | 'system', required
      - `space` string, nullable, required: Space id that initiated this run, if any.
      - `handler` string, nullable, required: Runtime handler that initiated this run, if any.
      - `visitor` boolean, required: Whether a signed-in Space visitor initiated this run.
      - `id` string, required: Run id (`cxr_`).
      - `input` object, required: What the run was asked to do, without echoing arguments that may carry customer data.
        - `kind` 'tool' | 'code', required: `tool` is one call; `code` is a program that may make many. Same endpoint, same id space, same resume.
        - `address` string, nullable, required: Tool address for a `tool` run; null for a `code` program.
        - `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.
        - `toolCalls` integer, required: Tool calls made so far.
        - `egressBytes` integer, required: Bytes read from third-party APIs so far.
        - `durationMs` integer, required: Wall-clock time spent executing so far.
      - `createdAt` string, date-time, required
      - `status` 'awaiting_approval', required: Parked on a decision.
      - `approval` object, required: A run waiting on a decision. Durable — any replica can resume it.
        - `decisionId` string, nullable, required: Grant-decision id (`gdc_`) backing this approval when the credential is grant-backed; null for session/API-key pauses (resume with the run id).
        - `mode` 'human' | 'model', required: Who may decide. Fixed when the run parked: `human` refuses machine resumes.
        - `address` string, required: Tool the run is waiting to call.
        - `preview` object, required: The arguments it would send, with secret-shaped values masked.
        - `reason` 'policy_require_approval' | 'annotation_requires_approval', required: Why it parked: a policy rule, or the tool's own annotation.
        - `matchedPattern` string, nullable, required: Policy pattern that parked it; null when the tool asked for itself.
        - `approvalUrl` string, uri, required: Dashboard page where a person approves or denies.
        - `expiresAt` string, date-time, required: After this the run expires and cannot be resumed.
    - object
      - `origin` 'dashboard' | 'cli' | 'api' | 'mcp' | 'zero' | 'function' | 'system', required
      - `space` string, nullable, required: Space id that initiated this run, if any.
      - `handler` string, nullable, required: Runtime handler that initiated this run, if any.
      - `visitor` boolean, required: Whether a signed-in Space visitor initiated this run.
      - `id` string, required: Run id (`cxr_`).
      - `input` object, required: What the run was asked to do, without echoing arguments that may carry customer data.
        - `kind` 'tool' | 'code', required: `tool` is one call; `code` is a program that may make many. Same endpoint, same id space, same resume.
        - `address` string, nullable, required: Tool address for a `tool` run; null for a `code` program.
        - `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.
        - `toolCalls` integer, required: Tool calls made so far.
        - `egressBytes` integer, required: Bytes read from third-party APIs so far.
        - `durationMs` integer, required: Wall-clock time spent executing so far.
      - `createdAt` string, date-time, required
      - `status` 'succeeded', required
      - `completedAt` string, date-time, required
      - `result` unknown, required
    - object
      - `origin` 'dashboard' | 'cli' | 'api' | 'mcp' | 'zero' | 'function' | 'system', required
      - `space` string, nullable, required: Space id that initiated this run, if any.
      - `handler` string, nullable, required: Runtime handler that initiated this run, if any.
      - `visitor` boolean, required: Whether a signed-in Space visitor initiated this run.
      - `id` string, required: Run id (`cxr_`).
      - `input` object, required: What the run was asked to do, without echoing arguments that may carry customer data.
        - `kind` 'tool' | 'code', required: `tool` is one call; `code` is a program that may make many. Same endpoint, same id space, same resume.
        - `address` string, nullable, required: Tool address for a `tool` run; null for a `code` program.
        - `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.
        - `toolCalls` integer, required: Tool calls made so far.
        - `egressBytes` integer, required: Bytes read from third-party APIs so far.
        - `durationMs` integer, required: Wall-clock time spent executing so far.
      - `createdAt` string, date-time, required
      - `status` 'failed', required
      - `completedAt` string, date-time, required
      - `error` object, required: Why it failed, as a problem document. The HTTP response is still 200: the request succeeded, the run did not.
        - `type` string, required: Problem type URI resolving to the error docs page. The server derives it mechanically from `code` against the docs origin.
        - `title` string, required: Short human-readable summary of the problem type. The server derives it mechanically from `code`.
        - `status` integer, required: HTTP status code of this response, repeated in the body.
        - `detail` string, required: Human-readable failure explanation for this occurrence.
        - `code` string, required: Stable snake_case error code naming the failed public contract.
        - `pointer` string: RFC 6901 JSON Pointer into the failing request field, for example "/files/37/path", on validation failures.
        - `details` object: Machine-readable context for the error code.
        - `suggestions` string[]: Actionable recovery steps safe to show in dashboards, SDKs, and CLI output.
        - `next` string[]: Copy-pasteable commands or API requests an agent can run next.
        - `requestId` string, required: The request id to quote when contacting support.
    - object
      - `origin` 'dashboard' | 'cli' | 'api' | 'mcp' | 'zero' | 'function' | 'system', required
      - `space` string, nullable, required: Space id that initiated this run, if any.
      - `handler` string, nullable, required: Runtime handler that initiated this run, if any.
      - `visitor` boolean, required: Whether a signed-in Space visitor initiated this run.
      - `id` string, required: Run id (`cxr_`).
      - `input` object, required: What the run was asked to do, without echoing arguments that may carry customer data.
        - `kind` 'tool' | 'code', required: `tool` is one call; `code` is a program that may make many. Same endpoint, same id space, same resume.
        - `address` string, nullable, required: Tool address for a `tool` run; null for a `code` program.
        - `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.
        - `toolCalls` integer, required: Tool calls made so far.
        - `egressBytes` integer, required: Bytes read from third-party APIs so far.
        - `durationMs` integer, required: Wall-clock time spent executing so far.
      - `createdAt` string, date-time, required
      - `status` 'expired', required: Parked too long. Submit it again; it cannot be resumed.
      - `completedAt` string, date-time, required

## Other responses

- `201`: Response for status 201
- `default`: Problem details (RFC 9457). Any 4xx/5xx response is one `application/problem+json` document.

---

[API](https://skmtc.dev/spacefast/apis/spacefast-api.md) · [All operations](https://skmtc.dev/spacefast/apis/spacefast-api/llms.txt) · [OpenAPI document](https://skmtc.dev/spacefast/apis/spacefast-api/revisions/bd165bc7c983?raw)