> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Jobs V1

> List jobs for the authenticated tenant. Mirrors the dashboard's /api/jobs/ filters + cursor pagination so v1 callers can enumerate their own runs without…

List jobs for the authenticated tenant.

Mirrors the dashboard's `/api/jobs/` filters + cursor pagination so v1
callers can enumerate their own runs without remembering every job id.

### Query parameters

<ParamField query="status" type="string,null">
  Filter to a single status: queued, running, succeeded, failed, cancelled, awaiting\_approval
</ParamField>

<ParamField query="template" type="string,null">
  Filter to a specific agent\_type / template name
</ParamField>

<ParamField query="search" type="string,null">
  Substring match against job id or summary
</ParamField>

<ParamField query="tag" type="string[],null">
  Filter to jobs that carry every supplied tag (AND-match). Repeat the parameter to require multiple tags: `?tag=env:prod&tag=owner:billing-team`.
</ParamField>

<ParamField query="sort" type="string">
  field:dir — field is one of created\_at|updated\_at|status|template|cost\_usd; dir is asc|desc
</ParamField>

<ParamField query="limit" type="integer" />

<ParamField query="offset" type="integer" />

<ParamField query="cursor" type="string,null">
  Opaque cursor from a previous response's X-Next-Cursor header. When set, supersedes `offset` and pages strictly past the seed row using a seek predicate. Only valid for sort=created\_at.
</ParamField>

### Response

`JobStatusResponse[]` — each element:

<ResponseField name="id" type="string" required>
  Job UUID.
</ResponseField>

<ResponseField name="status" type="string" required>
  Current status: queued, running, succeeded, failed, cancelled, awaiting\_approval.
</ResponseField>

<ResponseField name="template" type="string" required>
  Agent type / template that was used.
</ResponseField>

<ResponseField name="summary" type="string,null">
  Pipe-separated final assistant text. Populated when the job reaches a terminal state. Truncated to ≈5 segments × 280 chars.
</ResponseField>

<ResponseField name="error" type="string,null">
  Human-readable error message when status is 'failed' or 'cancelled'.
</ResponseField>

<ResponseField name="input_tokens" type="integer,null">
  Cumulative input tokens consumed.
</ResponseField>

<ResponseField name="output_tokens" type="integer,null">
  Cumulative output tokens generated.
</ResponseField>

<ResponseField name="cost_usd" type="number,null">
  Cumulative billable cost. Priced at the job's selected model rate (not the deployment default).
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 UTC timestamp.
</ResponseField>

<ResponseField name="updated_at" type="string" required>
  ISO 8601 UTC timestamp; refreshed on every iteration.
</ResponseField>

### Status codes

| Code  | Meaning             |
| ----- | ------------------- |
| `200` | Successful Response |
| `422` | Validation Error    |

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.computer.stateset.app/api/v1/jobs' \
    --header 'X-API-Key: YOUR_API_KEY'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "pending",
      "template": "string",
      "summary": "Two-person tent, green — replacement for damaged pole set.",
      "error": "string",
      "input_tokens": 1,
      "output_tokens": 1,
      "cost_usd": 1.5,
      "created_at": "2026-08-31T14:22:05Z",
      "updated_at": "2026-08-31T14:22:05Z"
    }
  ]
  ```
</ResponseExample>