# Requests and results

Reference for GET /v1/requests, GET /v1/requests/{id} and GET /v1/results/{id}. List your calls, poll a running request and re-read stored results for free.

Every call to `POST /v1/run/{sku}` creates a request with an id (`req_…`). These endpoints read them back. They are free, and they only ever show requests made by your own account: another account's id answers `404 not_found`, exactly like an id that does not exist.

## GET /v1/requests

`GET https://api.primaryapi.com/v1/requests`

Auth: API key with run, view or full access, or a dashboard session

Lists your requests, newest first.

### Query parameters

| Parameter | Type | Description |
|---|---|---|
| `limit` | integer | Page size, 1–200. Default 50. |
| `cursor` | string | `nextCursor` from the previous page. |
| `sku` | string | Only requests for this SKU. |
| `keyId` | string | Only requests made with this key. |
| `status` | string | `queued`, `running`, `succeeded`, `failed` or `expired`. |

### Response

**200 OK**: `{ "items": [...], "nextCursor": "…" | null }`, where each item is:

| Field | Type | Description |
|---|---|---|
| `requestId` | string | `req_…` |
| `sku` | string | The API called. |
| `status` | string | `queued`, `running`, `succeeded`, `failed` or `expired`. |
| `credits` | integer | Credits charged. `0` for failed and expired requests. |
| `items` | integer | Billable results. |
| `latencyMs` | integer or null | Time to the answer. |
| `keyId`, `keyName` | string or null | The key that made the call (null for dashboard calls). |
| `errorCode` | string or null | The error code of a failed request. |
| `createdAt` | string | ISO 8601 timestamp. |

```bash
curl -sS "https://api.primaryapi.com/v1/requests?status=failed&limit=20" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY"
```

```json title="200 OK"
{
  "items": [
    {
      "requestId": "req_01JBXR2V4X6Z8B0D2F4H6K8M0P",
      "sku": "email.verify",
      "status": "failed",
      "credits": 0,
      "items": 0,
      "latencyMs": 9120,
      "keyId": "key_01JBXM3T5V7Q9R2K4N6P8W0Y1Z",
      "keyName": "nightly-enrichment",
      "errorCode": "all_sources_failed",
      "createdAt": "2026-10-30T14:05:09.120Z"
    }
  ],
  "nextCursor": null
}
```

## GET /v1/requests/\{id\}

`GET https://api.primaryapi.com/v1/requests/{id}`

Auth: API key with run, view or full access, or a dashboard session

The current state of one request: the way to poll after a `202`. Guide: [Durable requests](/docs/durable-requests).

### Response

**200 OK**: a request snapshot.

| Field | Type | Present | Description |
|---|---|---|---|
| `requestId` | string | always | `req_…` |
| `sku` | string | always | The API called. |
| `status` | string | always | `queued`, `running`, `succeeded`, `failed` or `expired`. |
| `createdAt` | string | always | When the call started. |
| `finishedAt` | string or null | always | When it finished; `null` while running. |
| `retryAfterSeconds` | number | while running | Seconds to wait before polling again. |
| `expiresAt` | string or null | running, succeeded | While running: the deadline. After success: when the stored result will be deleted. |
| `credits` | integer | finished | Credits charged. |
| `result` | object | succeeded | The full envelope, while it is stored. |
| `resultExpired` | boolean | succeeded | `true` once the stored result was deleted (the metadata stays). |
| `error` | object | failed, expired | `{ code, message }`. Expired requests carry the code `timeout`. |

```json title="200 OK (running)"
{
  "requestId": "req_01JBXS6Z8B0D2F4H6K8M0P2R4T",
  "sku": "reddit.search",
  "status": "running",
  "createdAt": "2026-10-30T14:05:09.120Z",
  "finishedAt": null,
  "expiresAt": "2026-10-30T14:20:09.120Z",
  "retryAfterSeconds": 2
}
```

```json title="200 OK (failed)"
{
  "requestId": "req_01JBXR2V4X6Z8B0D2F4H6K8M0P",
  "sku": "email.verify",
  "status": "failed",
  "createdAt": "2026-10-30T14:05:09.120Z",
  "finishedAt": "2026-10-30T14:05:18.240Z",
  "credits": 0,
  "error": { "code": "all_sources_failed", "message": "Every source failed for this request. You were not charged." }
}
```

Errors: `404 not_found` for an unknown id or one that belongs to another account.

## GET /v1/results/\{id\}

`GET https://api.primaryapi.com/v1/results/{id}`

Auth: API key with run, view or full access, or a dashboard session

Returns the stored envelope of a succeeded request, for free: no upstream call and no charge. Use it to look at more fields or rows than you first asked for. Results are stored after the request finished for as long as your workspace's plan keeps them: 24 hours on Pay as you go, 7 days on Builder, 30 on Pro, 90 on Scale and Enterprise, fixed when the request was made ([Durable requests](/docs/durable-requests#stored-results)).

### Query parameters

The same trimming parameters as `POST /v1/run/{sku}`: `fields`, `max_items` and `summary`.

### Response

**200 OK**: the envelope, exactly as the original call returned it (before any trimming you applied then).

```bash
curl -sS "https://api.primaryapi.com/v1/results/req_01JBXS6Z8B0D2F4H6K8M0P2R4T?fields=title,permalink&max_items=10" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY"
```

Errors: `404 not_found` when the request does not exist or belongs to another account, while it is still running (the body carries `retryAfterSeconds`), when it failed or expired, and after its stored result was deleted.
