---
title: "List jobs"
method: GET
path: "/v1/jobs"
tags: ["jobs"]
---

# List jobs

`GET /v1/jobs`

## Request

- Base URL: `https://api.pomerado.ai`
- URL: `https://api.pomerado.ai/v1/jobs`
- Auth: HTTP bearer

List your runs and builds, newest first, each with its status, website, task and the question it asks.

- Lists the jobs you can read with GET /v1/jobs/{id}: those your API key, app or Dashboard started. The Dashboard lists the ones you started from any client.
- status filters by one or more statuses, comma-separated, such as status=needs_input. A filtered page can hold fewer jobs than limit, so follow next_cursor until it is null.
- q finds the jobs whose website or site name contains its text. Tasks are kept encrypted for you alone and can't be searched here; search them in the jobs you list.
- counts totals your jobs of the listed type by state, whatever status, q, cursor and limit asked for; needs_input_count repeats counts.needs_input.
- A job's result is never listed; read it with GET /v1/jobs/{id}.

## Query parameters

- `type` 'run' | 'build'
- `status` string
- `q` string
- `cursor` string
- `limit` string

## Response `200`

One page of jobs

- JobList
  - `data` JobSummary[], required
    - `id` string, required: a job ID: job_ and 32 lowercase hex digits
    - `type` 'run' | 'build', required
    - `build_kind` 'new' | 'change', nullable, required: A build of a new tool, or a requested change to an existing one; null for a run
    - `status` 'queued' | 'running' | 'needs_input' | 'succeeded' | 'failed' | 'cancelled', required
    - `stage` 'queued' | 'checking_login' | 'exploring' | 'building' | 'publishing', nullable, required: A build's current stage, or the one it ended in; null for a run
    - `site_url` string, nullable, required: The website's https origin the job was asked for
    - `site_name` string, nullable, required: The site's name: its tool's integration's, else the integration of its website; null until one names it
    - `task` string, nullable, required: A build's task or a requested change, its first 500 characters; GET /v1/jobs/{id} shows all of it. Null for a run
    - `question` string, nullable, required: The first question's prompt while the job asks one; answer it with GET /v1/jobs/{id}'s input_request
    - `waiting_since` string, nullable, required: When the question was asked, while the job asks one
    - `tool_id` string, nullable, required
    - `tool_name` string, nullable, required: The name of the tool tool_id names, such as the one a build published
    - `integration_id` string, required: an integration ID: int_ and 32 lowercase hex digits
    - `eta` object, nullable, required: How long builds usually take, in seconds from start to end, while this one is queued or running; null otherwise
      - `min_seconds` number, required
      - `max_seconds` number, required
    - `longer_than_usual` boolean: True when this build is queued or running and has run longer than usual. eta is null then
    - `watch_url` string, required
    - `created_at` string, required: a string to be decoded into a Date
    - `updated_at` string, required: a string to be decoded into a Date
    - `completed_at` string, required: a string to be decoded into a Date
  - `next_cursor` string, nullable, required
  - `needs_input_count` integer, required: an integer
  - `counts` JobCounts, required: How many of your jobs of the listed type are in each state, whatever status, q, cursor and limit asked for
    - `needs_input` integer, required: an integer
    - `in_progress` integer, required: an integer
    - `finished` integer, required: an integer

## Other responses

- `400`: invalid_request
- `401`: unauthorized, reauthentication_required
- `403`: forbidden
- `500`: internal_error
- `503`: temporarily_unavailable

---

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