--- title: "Read one run" method: GET path: "/v1/connectors/runs/{runId}" tags: ["Connectors"] --- # Read one run `GET /v1/connectors/runs/{runId}` ## Request - Base URL: `https://api.spacefast.com` - URL: `https://api.spacefast.com/v1/connectors/runs/{runId}` - 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:read`) Returns one run: its result, the problem document that explains a failure, or the approval it is parked on. ## Path parameters - `runId` string, required: Run id (`cxr_`). ## Query parameters - `team` string: Team id or slug to act for. Required only when the credential could act for more than one team. ## 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 - `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)