---
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 280 APIs across 51 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>`. Every MCP request needs a key or a sign-in. Without the header the server answers 401 and the client asks a person to sign in through the browser, which an agent working alone can't finish, so send the 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`, `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 (with your key): `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. |
| `connection_required` | This API reads your human's own account. Give them `details.connectUrl` to connect it, wait, then retry. Nothing was charged. |
| `connection_needs_reauth` | Your human's connected account must be reconnected. Give them `details.connectUrl`, then retry. Nothing was charged. |
| `connection_access_off` | Your human turned this API off for agents on this connected account (`details.source`, `details.capability`). Do not retry or work around it; tell them, and give them `details.settingsUrl` if they want to change it. Nothing was charged. |
| `approval_required` | A person must approve this call first. Give your human `details.approvalUrl` and say why you need it; once they approve, run the SAME call again with `approval: details.approvalId` (a different input needs a new approval). Do not loop. Nothing was charged. |
| `domains_not_allowed` | This workspace cannot buy domains yet (`details.missing`): ask your human to verify their email and to buy credits once in the dashboard, then retry. Nothing was charged. |
| `domain_suspended` | PrimaryAPI suspended this domain: you can read it, not change it. Tell your human; do not retry. |
| `domain_unavailable` | This name cannot be registered or transferred in (`details.reason`). Check other names with `POST /v1/domains/check`. Nothing was charged. |
| `domain_price_limit` | The order would cost more than `maxUsd`, or the price changed since your quote. Quote again, confirm the new price with your human if it is higher, and resend with `maxUsd`. Nothing was charged. |
| `domain_conflict` | The domain's state blocks this change (`details.reason`: custom nameservers, another order in progress, a pending registration). Fix that first; do not retry unchanged. |
| `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 or connected account in this workspace already has this `customId` (`details.monitorId` or `details.connectionId`). Use a different one, or change that one instead (`GET /v1/monitors/by-custom-id/{customId}` or `GET /v1/connections/by-custom-id/{customId}`, then PATCH it). |
| `invite_unavailable` | This connection invite link was already used, expired or was revoked. Create a new one with `POST /v1/connections/{provider}/invites`. |
| `approval_unavailable` | That approval was declined, already used, has expired, or is for another call (`details.status`). Run the call again without `approval` to get a new link for your human; if it was declined, ask them before trying again. |
| `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.

## 9. Private data: connected accounts

Some APIs (`github.my_repos`, `gmail.search`, `instagram.my_profile` …, tagged `private`) run as a GitHub, Google, Instagram or Cloudflare account that a person connected to the workspace. APIs marked `writes` change that account (a DNS record, a sitemap, an ad campaign): confirm with the person before running one. Your key needs access to connected accounts (an owner or admin grants it per key); without it you get `403 forbidden`.

- **Pick the account with `connection`.** It matches, in order: the connection id (`con_…`), its `customId` (exact), the account handle (any case), its `name` (any case). Prefer the `customId` or id: a handle or name can match two accounts, and then the call answers `400 invalid_input` with the candidates in `details.connections` (`id`, `label`, `name`, `customId`, `status`). With several accounts and no `connection`, you get the same 400.
- **List them:** `GET https://api.primaryapi.com/v1/connections?provider=instagram&q=acme`, or one by your own reference: `GET https://api.primaryapi.com/v1/connections/by-custom-id/{customId}`.
- **No account yet:** `403 connection_required` with `details.connectUrl`. Give the link to your human (a member of the workspace) and retry after they connect. Nothing was charged.
- **Agent access rules (MCP only):** through the MCP server each connection has rules per capability and API. By default reads run and APIs that change something ask a person. `approval_required`: give your human `details.approvalUrl`, then run the SAME call again with `approval: details.approvalId` (one call, same input, within 24 hours). `connection_access_off`: the rule is Off; tell your human (`details.settingsUrl`), do not work around it. Calls with an API key through the REST API always have full access. Nothing is charged for either refusal.
- **Connect a customer's account** (a key with `full` access and access to connected accounts): create an invite with your own reference and a `redirectUrl` (required), share its `url` with the customer yourself (PrimaryAPI never emails or contacts your customers: an invite is only a link), then call with that reference. The customer needs no PrimaryAPI account and never sees the `customId`.
- **Monitor an account:** `POST https://api.primaryapi.com/v1/monitors` with `"input": {"connection": "cust_1042"}`. Each monitor reads ONE account, kept by its id, so renames and new custom ids don't break it. Leave `connection` out only when a single account can run the API (with several: `400 invalid_input` and `details.connections`). Your key needs access to connected accounts to create or change it (`403 forbidden`, `details.reason: key_connections_access`). Disconnecting the account DELETES its monitors (reconnecting doesn't bring them back; `GET https://api.primaryapi.com/v1/monitors?connectionId={id}` lists them first). A `monitor.run.failed` event with `run.reason: connection_needs_reauth` names the account in `connection`: ask your human to reconnect it. The 10th failed run in a row pauses a monitor (`consecutiveFailures`, `failingSince`; a run also fails when its webhook was still undelivered after every retry); it is then paused (`pausedReason: failing`, and a failed call's event carries `monitorPaused`): fix the cause and PATCH `{"status": "active"}`. Event bodies of these monitors are deleted once delivered, by design, so redelivery answers `422 event_body_deleted`: run the monitor again instead.
- **Send the customer back to your product:** every invite needs `"redirectUrl": "https://app.example.com/integrations"`, a page in your product (https, or http://localhost while developing). There is no default and nothing is remembered from earlier invites; without it the invite answers `400 invalid_input` (`details[0].path: ["redirectUrl"]`). When they are done their page sends them there with `status=connected&connection_id=con_…&invite_id=cin_…`, or `status=error&error=<code>&invite_id=cin_…`; a used, expired or cancelled link only offers a return link with `error=invite_unavailable`. Your `customId` is never added. Verify with `GET https://api.primaryapi.com/v1/connections/{connection_id}` before trusting the parameters.
- **Hear about accounts instead of polling:** `POST https://api.primaryapi.com/v1/webhook-endpoints` with `{"url": "https://…", "events": [...]}` (a key with `full` access; at most 10 per workspace) receives signed `connection.connected` (`data.reconnected`, `data.invite`), `connection.needs_reauth` (once, on the change), `connection.disconnected` (`data.deletedMonitorIds`) and `connection.invite_expired` events, each with the account's or invite's `customId`. Drop duplicates by the event `id`. Every delivery keeps an attempt log: `GET https://api.primaryapi.com/v1/webhook-endpoints/{id}/deliveries/{deliveryId}` (and `GET https://api.primaryapi.com/v1/monitors/{id}/deliveries/{deliveryId}` for monitors) lists each attempt's time, duration, status or error (`timeout`, `connection_refused`, `tls_failed`, `dns_failed`, `blocked_url`, `http_503` …) and the first 1,024 bytes of the response. Event bodies are kept by plan (until delivered on Pay as you go, 7 to 90 days on a plan); redelivering one that is gone answers `422 unprocessable` (`details.reason: event_body_deleted`).

```bash
curl -sS -X POST "https://api.primaryapi.com/v1/connections/instagram/invites" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Acme Bakery", "customId": "cust_1042", "redirectUrl": "https://app.example.com/integrations"}' | jq -r .url
curl -sS -X POST "https://api.primaryapi.com/v1/run/instagram.my_profile" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" -H "Content-Type: application/json" \
  -d '{"connection": "cust_1042"}'
```

Invites are single use and expire after `expiresInDays` (1–30, default 7; an expired invite is stored as `expired` within about a minute and stays so). `GET /v1/connections/invites` shows each one's `status` (`pending`, `connected` with `connectionId`, `expired`, `revoked`); a used, expired or cancelled link answers `410 invite_unavailable`. Rename an account or set its `customId` with `PATCH /v1/connections/{id}` (`409 custom_id_taken` when another connection has it). Results of private-data APIs are kept like any call's, for the plan's result retention, so `GET /v1/results/{id}` re-reads them and an Idempotency-Key replays them (a monitor's webhook event is still kept encrypted only until it is delivered).

## APIs at a glance

- Social (143 APIs): Bluesky, Hacker News, Instagram, Link-in-bio, LinkedIn, Naver, Nextdoor, Pinterest, Reddit, RedNote, Snapchat, Social, and 7 more
- Search & SEO (12 APIs): Bing Webmaster Tools, Google Maps
- Knowledge & Data (18 APIs): Banks (FDIC), ClinicalTrials.gov, GitHub, Jobs, Lottery, MCP, Sports, Vehicles (VIN)
- Video (1 API): Video
- E-commerce (7 APIs): TikTok Shop
- Validation (6 APIs): Email, IP, NPI Registry, Phone
- Compliance & Records (13 APIs): Company, FDA, Federal Register, Product Recalls, Sanctions Lists
- Web Intelligence (64 APIs): Ad Libraries, API, Domain, Facebook, TikTok, USAspending, Vendor Status, Website
- Audio (5 APIs): Spotify
- Web Scraping (11 APIs): Cloudflare, 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; connected accounts too; paused after 10 failed runs in a row): https://primaryapi.com/docs/md/monitors
- Webhooks: monitor events, webhook endpoints and connection events, attempt logs, signatures, retries and retention: https://primaryapi.com/docs/md/webhooks
- Connected accounts and customer invites: https://primaryapi.com/docs/md/connected-accounts
- Everything in one file: https://primaryapi.com/llms-full.txt
