Run and quote
Reference for POST /v1/run/{sku} and POST /v1/quote/{sku}. Path, headers, query parameters, body, every response shape and status code.
Last updated
On this page
POST /v1/run/{sku}
api.primaryapi.com/ v1/ run/ {sku}Auth: API key with run or full access, or a dashboard session
Runs one API. The call is routed to a healthy upstream at the best price and retried automatically if an attempt fails; you pay only for the answer. Guide: Making requests.
Path
| Parameter | Description |
|---|---|
sku | The API to run, for example reddit.search. Case-insensitive. Unknown, planned and deprecated SKUs answer 404 not_found. |
Headers
| Header | Required | Description |
|---|---|---|
Authorization or X-API-Key | yes | Bearer pa_live_…, or the bare key in X-API-Key. |
Content-Type | yes | application/json |
Idempotency-Key | no | 1–255 visible ASCII characters. Makes retries safe (Idempotency). |
Prefer | no | respond-async, wait=N (seconds, at most 90) or both, comma-separated (Durable requests). |
Query parameters
All optional. They shrink the response body only; the charge, items and the stored result are unchanged.
| Parameter | Type | Description |
|---|---|---|
fields | string | Comma-separated top-level keys of output.data (or of each row of a list result) to keep. At most 100 names. |
max_items | integer | Keep at most this many rows of a list result. |
summary | boolean | true returns an outline: arrays become { "count": n }, strings over 120 characters are cut. |
Body
A JSON object (at most 2 MB) with the SKU's input fields, as listed in its inputSchema and on its reference page, plus any routing controls:
| Field | Type | Description |
|---|---|---|
maxCredits | integer | The most this call may cost, in whole credits; caps the credits held for it. If the API cannot serve this input within it, 400 invalid_input. |
preferLatencyUnderMs | integer | Prefer answers within this many milliseconds (best effort; never refuses the call). |
Unknown input fields are rejected. The retired controls source, allowFallbacks and ignoreSources are accepted and ignored. The dollar cap maxCostUsd was replaced by maxCredits and is refused with 400 invalid_input. Details: Routing and failover.
Responses
200 OK: the call finished. The body is the envelope:
| Field | Type | Description |
|---|---|---|
output.found | boolean | Whether the requested data exists. |
output.data | object or null | The result, shaped by the SKU's outputSchema; null when not found. |
output.reason | string | When found is false: not_found, private, suspended, no_results, … |
provider | string | Always PrimaryAPI. |
credits | integer | Credits charged for this call; 0 when nothing was charged. |
items | integer | Billable results. |
requestId | string | req_… |
nextCursor | string or null | List APIs: cursor for the next page. |
hint | string | Optional advisory note, for example truncated: …. |
replayed | boolean | true for an idempotent replay (no charge). |
Headers: X-Request-Id; Idempotency-Replayed: true|false when an Idempotency-Key was sent.
202 Accepted: still running at the end of the wait window. The body is a request snapshot (see GET /v1/requests/{id}); headers Location: /v1/requests/{id}, Retry-After, X-Request-Id, and Preference-Applied when a Prefer value was honoured.
Errors (never charged):
| Status | Codes |
|---|---|
| 400 | invalid_input |
| 401 | unauthorized, key_disabled, key_expired |
| 402 | insufficient_balance, key_limit_reached, trial_cap_reached |
| 403 | forbidden, restricted_api |
| 404 | not_found |
| 409 | idempotency_conflict |
| 422 | unprocessable |
| 429 | rate_limited |
| 500 | internal_error |
| 502 | all_sources_failed |
| 503 | service_unavailable |
| 504 | timeout |
Example
curl -sS -X POST "https://api.primaryapi.com/v1/run/reddit.search?fields=title,score&max_items=3" \
-H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6c2f6a9e-0b2d-4d1b-9a77-3f5e8c1d2b40" \
-H "Prefer: wait=20" \
-d '{"query":"best mechanical keyboard","limit":10,"maxCredits":5}'const res = await fetch('https://api.primaryapi.com/v1/run/reddit.search?fields=title,score&max_items=3', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.PRIMARYAPI_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
Prefer: 'wait=20',
},
body: JSON.stringify({ query: 'best mechanical keyboard', limit: 10, maxCredits: 5 }),
});
const body = await res.json(); // 200: envelope · 202: snapshot · otherwise { code, error, requestId }import os
import uuid
import requests
res = requests.post(
"https://api.primaryapi.com/v1/run/reddit.search",
params={"fields": "title,score", "max_items": 3},
headers={
"Authorization": f"Bearer {os.environ['PRIMARYAPI_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
"Prefer": "wait=20",
},
json={"query": "best mechanical keyboard", "limit": 10, "maxCredits": 5},
timeout=30,
)
body = res.json() # 200: envelope · 202: snapshot · otherwise {code, error, requestId}{
"output": {
"found": true,
"data": {
"posts": [
{ "title": "…", "score": 412 },
{ "title": "…", "score": 388 },
{ "title": "…", "score": 251 }
],
"nextCursor": "eyJhZnRlciI6InQzXzFhYmMyMyJ9"
}
},
"provider": "PrimaryAPI",
"credits": 2,
"items": 1,
"requestId": "req_01JBXK6Y2N9V8T4R3Q2P1M0A7Z",
"nextCursor": "eyJhZnRlciI6InQzXzFhYmMyMyJ9",
"hint": "truncated: returned 3 of 10 items (max_items); credits cover the full result"
}POST /v1/quote/{sku}
api.primaryapi.com/ v1/ quote/ {sku}Auth: API key with run or full access, or a dashboard session
Validates a body exactly like a run (same input and routing checks, same 400, 404, 502 and 503 errors) and returns the price in credits. It never calls an upstream and never charges. Headers and body are the same as for a run; Idempotency-Key, Prefer and the trimming parameters are ignored.
Response
200 OK:
| Field | Type | Description |
|---|---|---|
sku | string | The SKU quoted. |
credits | integer | The expected price of this call, in credits: the best available price for this input. |
maxCredits | integer | The most it can cost: what a run holds from your balance (the unused part comes back at once). A call is never charged more. |
unit | string | request or result. |
inputValid | boolean | Always true (invalid input answers 400). |
Example
curl -sS -X POST "https://api.primaryapi.com/v1/quote/facebook.search_posts" \
-H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"product launch","limit":5}'{
"sku": "facebook.search_posts",
"credits": 17,
"maxCredits": 33,
"unit": "result",
"inputValid": true
}Credits in examples are illustrative; each API's reference page shows its current price.