> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: "List runs (gateway)"
description: "List runs with a service key, filtered by status, component, and time."
method: "GET"
endpoint: "/v1/runs"
order: 10
group: "Gateway: follow a run"
last_verified: 2026-10-08
---



`GET /v1/runs`

List runs with a service key, filtered by status, component, and time.


  ## Parameters

  - `X-API-KEY` _header_ **required** — A service key.
  - `status` _string_ — `queued`, `started`, `paused`, `completed`, `failed`, or `cancelled`. Any other value returns `400`.
  - `component_name` _string_ — Filter by component name.
  - `component_type` _string_ — Filter by component type.
  - `since_ms` _integer_ — Only runs at or after this epoch-millisecond timestamp.
  - `until_ms` _integer_ — Only runs at or before this epoch-millisecond timestamp.
  - `limit` _integer_ — Maximum runs to return. Default 50.
  - `cursor` _string_ — The `next_cursor` from the previous page.



  ## Request example


```bash
curl "https://gw.agnt5.com/v1/runs?status=completed&component_name=order_workflow&limit=20" \
  -H "X-API-KEY: {service_key}"
```

```javascript
fetch('https://gw.agnt5.com/v1/runs?status=completed&limit=20', {
  headers: { 'X-API-KEY': serviceKey }
})
```


  ```json {{ title: 'Response' }}
  {
    "items": [
      {
        "id": "7f6e5d4c-...",
        "component_name": "order_workflow",
        "component_type": "workflows",
        "status": "completed",
        "deployment_id": "8a1c2d3e-...",
        "duration_ms": 2166,
        "error_type": null,
        "error_message": null
      }
    ],
    "has_more": true,
    "limit": 20,
    "next_cursor": "1791482664537:7f6e5d4c-..."
  }
  ```