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

# List your jobs

> Find your runs and builds, and which of them wait on an answer.

List your runs and builds with `GET /v1/jobs`. MCP clients call it through `call_pomerado_api`. Jobs come newest first, each with its status, website, task and the question it's waiting on.

```bash theme={null}
curl "https://api.pomerado.ai/v1/jobs?type=build&status=needs_input,running" \
  -H "Authorization: Bearer $POMERADO_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "id": "job_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
      "type": "build",
      "build_kind": "new",
      "status": "needs_input",
      "stage": "exploring",
      "site_url": "https://library.example.com",
      "site_name": null,
      "task": "Reserve a book for pickup",
      "question": "Which branch should hold the book?",
      "waiting_since": "2026-10-11T17:02:10.000Z",
      "tool_id": null,
      "tool_name": null,
      "integration_id": null,
      "eta": null,
      "watch_url": "https://app.pomerado.ai/builds/job_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
      "created_at": "2026-10-11T17:00:00.000Z",
      "updated_at": "2026-10-11T17:02:10.000Z",
      "completed_at": null
    }
  ],
  "next_cursor": null,
  "needs_input_count": 1,
  "counts": { "needs_input": 1, "in_progress": 2, "finished": 14 }
}
```

## Filter and page

* `type`: `run` or `build`.
* `status`: one or more [statuses](/guides/jobs/job-object#check-the-status), comma-separated.
* `q`: only jobs whose website or site name contains this text, ignoring case, such as `q=library`. Up to 200 characters.
* `limit`: jobs per page, 1 to 50 (20 by default).
* `cursor`: the `next_cursor` of the page before.

A filtered page can hold fewer jobs than `limit`, even none, while more follow. Keep following `next_cursor` until it is `null`.

`counts` totals your jobs of the listed type by state, whatever `status`, `q`, `cursor` and `limit` you asked for: `needs_input` waiting on an answer now, `in_progress` queued or running (each counted up to 100), and `finished` (up to 1,000). Use `counts.needs_input` for a badge, then [answer them](/guides/jobs/answer-questions). `needs_input_count` is the same number.

<Accordion title="Details">
  * The list shows the jobs you can read with `GET /v1/jobs/{id}`: the ones your API key or app started. The Dashboard lists the ones you started from any client.
  * `task` is a build's task or requested change, cut to 500 characters; `GET /v1/jobs/{id}` has all of it. It is `null` for runs. Pomerado keeps it encrypted, and only you can read it, so `q` doesn't search it: search tasks in the jobs you've listed.
  * `site_name` is what the site is called once one of your integrations, or a public one, names it. `tool_name` names the job's tool, such as the one a build published.
  * `waiting_since` says when the job asked its question. `eta` is how long builds usually take from start to end, in seconds, shown while a build is queued or running and Pomerado has enough recent builds to tell.
  * `question` is the first question's prompt. Read the job for its `input_request` before you answer. Listing a job changes nothing about it.
  * A listed job never carries its result, and listing it doesn't use the result up. Read the result with `GET /v1/jobs/{id}`.
  * Listing needs the `jobs:read` permission; see [permissions](/guides/authentication/permissions).
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.