# 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.

## POST /v1/run/\{sku\}

`POST https://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](/docs/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](/docs/idempotency)). |
| `Prefer` | no | `respond-async`, `wait=N` (seconds, at most 90) or both, comma-separated ([Durable requests](/docs/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](/docs/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\}](/docs/api-reference/requests#get-v1requestsid)); 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

```bash tab="cURL"
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}'
```

```ts tab="TypeScript"
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 }
```

```python tab="Python"
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}
```

```json title="200 OK"
{
  "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\}

`POST https://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

```bash
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}'
```

```json title="200 OK"
{
  "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.
