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.
Last updated
On this page
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
api.primaryapi.com/ v1/ requestsAuth: 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. |
curl -sS "https://api.primaryapi.com/v1/requests?status=failed&limit=20" \
-H "Authorization: Bearer $PRIMARYAPI_API_KEY"{
"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}
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.
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. |
{
"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
}{
"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}
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).
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).
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.