---
name: primaryapi
description: Fetch live third-party data through PrimaryAPI, one API key and one balance of prepaid credits in front of many pay-per-call data APIs (social profiles and posts, search results, company and people enrichment, e-commerce, maps and reviews, public records, email and phone validation, web pages). Use it whenever a task needs data from an online platform or a lookup or validation service. Covers getting a key (including a self-service trial key), finding the right API, checking prices, running calls over REST or MCP, keeping responses small, polling slow calls and handling every error.
---

# PrimaryAPI

PrimaryAPI is one HTTP API in front of many paid data providers. Each API is a **SKU** named `<platform>.<action>`, for example `instagram.profile`, `reddit.search` or `email.verify`. Every SKU is called the same way, `POST https://api.primaryapi.com/v1/run/{sku}`, with one API key. Each call is routed to a healthy upstream and retried automatically when an attempt fails, and credits are charged only when the call succeeds (most calls cost 1 or 2). The catalog currently lists 200 APIs across 31 platforms in 10 categories.

- API base URL: `https://api.primaryapi.com`
- MCP server (optional): `https://api.primaryapi.com/mcp`
- Docs for agents: https://primaryapi.com/llms.txt (index) and https://primaryapi.com/docs/md/<page> (any page as Markdown)

## Ground rules

1. **Never reveal the key.** Do not print, echo, log, paste or commit the API key (it starts with `pa_live_`), and never put it in a URL. Read it from `PRIMARYAPI_API_KEY` and send it only in the `Authorization: Bearer` header. In commands you show to a human, keep `$PRIMARYAPI_API_KEY` unexpanded.
2. **Read the contract before the first call of a SKU** (`GET /v1/apis/{sku}` or the MCP tool `get_api`). Input field names are exact; unknown fields are rejected with a free `400 invalid_input`.
3. **`output.found: false` is an answer, not a failure.** The thing does not exist, is private, or the search matched nothing. Report it and move on; do not retry it. It is normally free.
4. **Never re-run a call to wait for it.** A `202` (MCP: status "running") means it is still working: poll `GET /v1/requests/{id}` (MCP `get_request`). Running it again starts, and bills, a second job.
5. **Spend deliberately.** Prices are in credits, per call or per result. Quote first (`POST /v1/quote/{sku}`, free) when cost matters, cap a call with `maxCredits` if you need to, keep `limit` as low as the task allows, and stay inside the budget your human set.
6. **Keep responses small.** Ask only for the fields and rows you need (`fields`, `max_items`). Re-read a stored result for free instead of running the call again.
7. **On `402 trial_cap_reached`, stop and give your human `upgrade.claimUrl`.** Never create more trial keys to get around a cap.

## 1. Get a key

**A key you were given.** Look for `PRIMARYAPI_API_KEY` in the environment (or the project's git-ignored `.env`). Check it without spending anything:

```bash
curl -sS -o /dev/null -w '%{http_code}\n' "https://api.primaryapi.com/v1/requests?limit=1" -H "Authorization: Bearer $PRIMARYAPI_API_KEY"
```

`200` means the key works. `401` means it is missing, wrong, revoked, disabled or expired: ask your human. A `view` key passes this check but cannot run APIs (`403 forbidden`).

**No key: mint a trial key yourself.** `POST https://api.primaryapi.com/agent/signup` needs no account and no human. It returns a key with a small budget of credits (`capCredits`) that expires after 7 days unless a human claims it. Store the secret without printing it, and relay the `notice` to your human word for word:

```bash
resp=$(curl -sS -X POST "https://api.primaryapi.com/agent/signup" -H "Content-Type: application/json" -d '{"label":"<your agent name and task>"}')
export PRIMARYAPI_API_KEY="$(printf '%s' "$resp" | jq -r .secret)"
printf 'PRIMARYAPI_API_KEY=%s\n' "$PRIMARYAPI_API_KEY" >> .env   # only if .env is git-ignored; otherwise use your secret store
printf '%s\n' "$resp" | jq -r .notice           # tell your human this, verbatim
```

A trial key can search, quote and run APIs and read its own requests. It cannot read the workspace balance or call restricted APIs. One network can create 3 trial keys per 24 hours: reuse yours.

**MCP (optional).** If your client supports MCP, add `https://api.primaryapi.com/mcp` (Streamable HTTP) with the header `Authorization: Bearer <key>`. For Claude Code:

```bash
claude mcp add --transport http --scope user primaryapi https://api.primaryapi.com/mcp --header "Authorization: Bearer $PRIMARYAPI_API_KEY"
```

Tools: `search_apis`, `list_apis`, `get_api` (no key needed), `quote_api`, `run_api`, `get_request`, `read_result`, `get_balance`, `report_bug`, `send_feedback`. Setup for Claude Desktop, Cursor, Codex and VS Code: https://primaryapi.com/docs/md/mcp-server

## 2. Find the right API

Search the APIs (no key needed):

```bash
curl -sS "https://api.primaryapi.com/v1/apis?q=verify%20email&limit=5" | jq -r '.items[] | [.sku, .status, "\(.fromCredits) credits \(.priceModel)", .summary] | @tsv'
```

Then read the contract of the SKU you picked:

```bash
curl -sS "https://api.primaryapi.com/v1/apis/email.verify" | jq '{inputSchema, output: (.outputSchema.properties | keys), examples, price, maxCredits, health}'
```

- Only `live` and `beta` APIs can be called; `planned` ones answer `404 not_found`.
- `restricted: true` APIs need an approved account (`403 restricted_api` otherwise).
- `price` is what a call normally costs, in credits: `{"model": "per_call", "credits": 2}`, or for per-result APIs `{"model": "per_result", "creditsPerResult": 0.56, "minCredits": 1}` (plus `baseCredits` when a call has a fixed part: a call with n results costs `baseCredits + creditsPerResult × n` rounded up to whole credits, at least `minCredits`). `fromCredits` is the same figure and `maxCredits` the ceiling on the same basis, what a call can cost when it is retried elsewhere. `health` is the live 30-day status (`operational`, `degraded`, `outage`, `unknown`) with success rate, uptime and latency.
- MCP: `search_apis {"query": "…"}`, then `get_api {"sku": "…"}`.
- Nothing fits? Ask for it: `POST /v1/api-requests` with `{"name": "…", "message": "…"}` (no key), or MCP `send_feedback` with `kind: "api_request"`.

## 3. Check the price (free, optional)

```bash
curl -sS -X POST "https://api.primaryapi.com/v1/quote/email.verify" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" -H "Content-Type: application/json" \
  -d '{"email":"jane.doe@acme.com"}'
```

The answer has `credits` (what the call is expected to cost) and `maxCredits` (the most it can cost, which is set aside while the call runs; the unused part comes back at the end). For per-result APIs the price grows with `limit`.

## 4. Run it

```bash
curl -sS -X POST "https://api.primaryapi.com/v1/run/email.verify" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"email":"jane.doe@acme.com"}'
```

(`email.verify` currently costs 1 credit per call.) Use one `Idempotency-Key` per logical call and reuse it on every retry of that call, so a retry never runs or bills twice. MCP: `run_api {"sku": "…", "input": {…}, "fields": […], "max_items": N, "idempotencyKey": "…"}`; the SKU's fields go inside `input`.

A finished call answers `200`:

```json
{ "output": { "found": true, "data": { "…": "…" } }, "provider": "PrimaryAPI", "credits": 1, "items": 1, "requestId": "req_…" }
```

- `output.data` follows the SKU's `outputSchema`. `credits` is what this call cost (0 when nothing was charged). Keep `requestId` for re-reads and bug reports.
- `output.found: false` with `reason` (`not_found`, `private`, `no_results`, …): a valid answer. Report it.
- `nextCursor` (list APIs): send the same input again with `"cursor": "<nextCursor>"` for the next page; `null` means the end. Every page is billed on its own.
- `hint`: an optional advisory note, for example `truncated: …` after `max_items`.

## 5. Slow calls

If the call is not done within 10 seconds you get `202 Accepted` with `{"requestId": "…", "status": "running", "retryAfterSeconds": 2}`. The call keeps running. Poll `GET /v1/requests/{requestId}` every `retryAfterSeconds` (back off for long jobs) until `status` is `succeeded` (the envelope is in `result`), `failed` or `expired` (both cost nothing). To wait longer in one request instead, send `Prefer: wait=60` (at most 90). Requests have a 15-minute deadline.

## 6. Keep your context small

- `?fields=a,b` keeps only those top-level keys of `output.data` (of each row for list results).
- `?max_items=N` keeps the first N rows of a list result; `?summary=true` returns an outline (arrays become counts, long strings are cut).
- These shrink the response, **not the bill**: the call still fetches what the input asked for. To pay for fewer results, lower `limit`.
- The full result stays stored for as long as the workspace's plan keeps results (24 hours on Pay as you go, 7 to 90 days on a plan): re-read it for free with `GET /v1/results/{requestId}?fields=…&max_items=…` (MCP `read_result`).

## 7. Errors

Errors look like `{"code": "…", "error": "…", "requestId": "…"}` and are never charged. Branch on `code`, never on the message.

| Code | What to do |
|---|---|
| `invalid_input` | Read `details` (every issue with its path), fix the input against `inputSchema`, retry. Do not resend it unchanged. |
| `unauthorized` | The key is missing, mistyped or revoked. Check `PRIMARYAPI_API_KEY`; ask your human for a working key or mint a trial key. |
| `key_disabled` | Someone disabled this key. Ask your human to re-enable it or give you another key. |
| `key_expired` | The key expired (trial keys after 7 days). Ask your human to open the claim link, or mint a new trial key if none was ever claimed. |
| `insufficient_balance` | The balance cannot cover the most this call can cost (its quote's `maxCredits`). Ask your human to buy credits at https://primaryapi.com/dashboard/settings/billing; a smaller `limit` lowers what the call can cost. |
| `trial_cap_reached` | Your trial credits are used up. Give your human `upgrade.claimUrl` from the error body and wait for approval; then retry the same call. Do not create another trial key. |
| `key_limit_reached` | This key's spend limit for the current window is used up (`details.windowResetsAt`). Ask your human to raise it, or wait. |
| `forbidden` | The key cannot do this: a `view` key cannot run APIs, a `run` key cannot read billing or manage keys. Ask for a key with the right access. |
| `insufficient_scope` | Your OAuth access token was not granted the scope this endpoint needs (`details.requiredScopes`). Ask your human to authorize the app again with that scope. |
| `restricted_api` | This API needs an approved account. Tell your human, and pick a non-restricted API meanwhile. |
| `not_found` | Unknown SKU or request id (this is not "data not found"). Search again with `GET /v1/apis?q=…`. |
| `idempotency_conflict` | You reused an `Idempotency-Key` for a different request. Use a new key for new work. |
| `custom_id_taken` | Another monitor in this workspace already has this `customId` (`details.monitorId`). Use a different one, or change that one instead (`GET /v1/monitors/by-custom-id/{customId}`, then PATCH it). |
| `unprocessable` | This API cannot serve this particular input. Change the input; do not retry it unchanged. |
| `rate_limited` | Wait for `Retry-After` seconds, then retry with the same `Idempotency-Key`. Slow down. |
| `internal_error` | Retry with backoff and the same `Idempotency-Key`. If it persists, report it with the `requestId`. |
| `all_sources_failed` | The call could not be answered, even after automatic retries, and nothing was charged. Retry later with backoff (same `Idempotency-Key`). |
| `service_unavailable` | This API cannot run right now. Retry later or choose another API. |
| `timeout` | The call ran out of time and nothing was charged. Retry with the same `Idempotency-Key`, or send `Prefer: respond-async` and poll. |

Retry only `rate_limited`, `internal_error`, `all_sources_failed`, `service_unavailable` and `timeout` unchanged, with backoff and the same `Idempotency-Key`. Full details: https://primaryapi.com/docs/md/errors

## 8. Report problems

Wrong data, a schema mismatch or an error that looks like ours: `POST https://api.primaryapi.com/v1/bug-reports` with `{"message": "…", "requestId": "req_…", "sku": "…"}` (any key), or MCP `report_bug`. It is free and needs no human attention. Never include the key.

## APIs at a glance

- Social (113 APIs): Bluesky, Hacker News, Instagram, Link-in-bio, Naver, Nextdoor, Pinterest, Reddit, RedNote, Snapchat, Social, Substack, and 6 more
- Search & SEO (2 APIs): Google Maps
- Knowledge & Data (7 APIs): Banks (FDIC), GitHub
- Video (1 API): Video
- E-commerce (7 APIs): TikTok Shop
- Validation (4 APIs): Email, Phone
- Compliance & Records (1 API): Sanctions Lists
- Web Intelligence (59 APIs): Ad Libraries, Facebook, TikTok
- Audio (5 APIs): Spotify
- Web Scraping (1 API): Linktree

Browse every API with prices: https://primaryapi.com/docs/md/api-reference

## More

- Making requests: https://primaryapi.com/docs/md/making-requests
- Routing controls (latency preference, credit cap): https://primaryapi.com/docs/md/routing-and-failover
- Durable requests and polling: https://primaryapi.com/docs/md/durable-requests
- Idempotency and retries: https://primaryapi.com/docs/md/idempotency
- Agent trial keys and the claim flow: https://primaryapi.com/docs/md/agent-signup
- Monitors (run an API on a schedule, results to your webhook; paused after 10 failed runs in a row): https://primaryapi.com/docs/md/monitors
- Webhooks: monitor events, attempt logs, signatures, retries and retention: https://primaryapi.com/docs/md/webhooks
- Everything in one file: https://primaryapi.com/llms-full.txt
