---
title: "List runs"
method: GET
path: "/v1/connectors/runs"
tags: ["Connectors"]
---

# List runs

`GET /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:read`)

Returns the team's runs, newest first. `status=awaiting_approval` is the approvals inbox query.

## Query parameters

- `limit` integer: Page size.
- `cursor` string: Opaque cursor from the previous page's `nextCursor`.
- `origin` 'dashboard' | 'cli' | 'api' | 'mcp' | 'zero' | 'function' | 'system'
- `space` string: Filter by Space id.
- `status` 'running' | 'awaiting_approval' | 'succeeded' | 'failed' | 'expired': `awaiting_approval` is the approvals inbox query.
- `connection` string: Show only runs that touched this connection.
- `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
    - union: 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
  - `pagination` object, required
    - `nextCursor` string, nullable, required: Opaque cursor for the next page; null when there are no more results.
    - `hasMore` boolean, required: Whether another page exists after this one.

## 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)