Getting started
API.SH turns public web pages into JSON. There are 6,085 endpoints across 918 platforms, all plain GET requests with the same authentication, response shape and error format. Pick one from the docs menu or the catalog.
1. Get a key
Sign up, confirm your email (you get 1,000 free credits every month), and create a key under API keys. Keys look like ash_live_…. Keep them on your server: anyone with a key can spend its credits. Give each key an expiry date, a monthly cap or a list of allowed endpoints if you like: see API keys.
2. Make a call
curl "https://api.api.sh/reddit/v1/subreddit?subreddit=python" \
-H "x-api-key: $APISH_KEY" The base URL is https://api.api.sh. Every endpoint is /<platform>/v1/<resource> with its inputs as query parameters.
Authentication
Send your key in the x-api-key header (or Authorization: Bearer <key>). Requests without a valid key (missing, unknown, revoked or expired) get 401. Revoking or editing a key in the dashboard takes effect within about a minute.
Responses
Responses are JSON objects. Clean, stable fields come first (ids, names, counts, prices, dates, media URLs). Items and detail pages also carry raw: the complete data the site itself sent, so nothing is lost. Field names inside raw are the site's own and can change when the site changes; the clean fields keep their names.
Every data response also includes:
| field / header | meaning |
|---|---|
credits_used | Credits this call cost (0 for refused calls and failures on our side). |
cached, fetched_at | Whether the response came from the 24-hour cache, and when the data was fetched from the source. |
x-request-id header | The call's id. It's in your logs; quote it when you contact support. |
x-credits-used, x-credits-remaining headers | Credits charged, and your balance after the call. |
Errors
Errors use the HTTP status and a JSON body: {"success": false, "error": "…"}. Calls we refuse before running them (bad parameters, keys, credits, your limits) and failures on our side are free; a lookup that ran but found nothing, like a username that doesn't exist, costs the endpoint's price. See what's charged.
| status | meaning | what to do |
|---|---|---|
400 | A parameter is missing or invalid. | Check the endpoint's parameters. |
401 | Missing, invalid, revoked or expired API key. | Send a valid key in x-api-key. |
402 | Not enough credits (the body has credits_required and credits_remaining), or a spend limit or key cap you set was reached. | Add credits or change the limit. |
403 | This key isn't allowed to call this endpoint, or not from this network. | Check the key's settings. |
404 | The thing you asked for doesn't exist (or isn't public; the lookup ran, so it's charged), or the route is unknown (free). | Check the input. |
429 | Your team's contract rate or concurrency limit. | Retry after retry-after. |
502 | The source site failed or refused us this time. | Retry after a short wait. |
503 | The endpoint is paused or temporarily unavailable. May include retry-after. | Retry later; see status. |
Every status, its exact messages and how to retry: Errors.
Credits
Each endpoint has a price in credits, shown on its docs page and in the catalog. Prices reflect how heavy a source is to fetch: most endpoints cost 1 credit, heavier pages a few more. Each price is published per endpoint and reviewed periodically, so prices stay stable from day to day. Google search costs its price for every 10 results requested with limit. You pay for calls that run: successful (200) calls and lookups that found nothing (404). Refused calls and failures on our side are free.
Credits come from top-ups ($1 = 500 credits, never expire) or a monthly plan ($1 = 1,000 credits, reset at each renewal), plus 1,000 free credits every month for every account. Credits that expire soonest are spent first: your free monthly credits and plan credits (whichever resets sooner), then pay-as-you-go credits, which never expire. Plans, auto top-up, alerts and invoices: Billing and credits.
Caching
Successful responses are cached for 24 hours. A repeat call with the same parameters returns the stored copy in milliseconds with cached: true and costs the same as a live call. Add fresh=1 to skip the cache and fetch live; the new result replaces the cached one.
Lean responses
Any endpoint accepts two options that make responses smaller without an extra fetch:
raw=0leaves out therawblocks, often 10–30× smaller.fields=a,b,items.creturns only the listed fields.fields=posts.id,posts.titlekeeps those fields of each post.
Call metadata (cached, fetched_at, credits_used, next_*) is always included.
Pagination
List endpoints paginate with page / next_page or cursor / next_cursor (some use after, offset or start, noted on their page). Pass the next_* value from the previous response; a null value means the last page.
Rate limits, concurrency and timeouts
Your keys have no rate limit and no cap on parallel calls. Most calls return in 1–3 seconds. A few endpoints can take up to a minute. Set your HTTP client timeout to at least 120 seconds. Enterprise teams can choose to have a request-rate or concurrency limit in their contract, answered with 429 and retry-after (never charged). If a site starts refusing requests we pause that endpoint briefly and return 503 with retry-after rather than charging you for failures. For very high volumes, tell us first so we can plan capacity.
CSV and NDJSON
Add output=csv or output=ndjson to any endpoint to get its records instead of JSON: the response's main list (search results, reviews, posts…) becomes one row per item, and a single item (a profile, a product) becomes one row. Nested fields are flattened to dot.paths in CSV; lists of plain values are joined with |. Pick the list with records=reviews, or records=. for the whole object as one row. Errors stay JSON. Price and caching are the same as for JSON.
curl "https://api.api.sh/amazon/v1/search?q=headphones&output=csv" \
-H "x-api-key: $APISH_KEY" -o headphones.csv Account API
Free endpoints (no credits) for your own account, with the same key:
| endpoint | returns |
|---|---|
GET /v1/account | Credits by bucket (free monthly, plan, pay-as-you-go), your plan, credits spent today and this month (UTC), your spend limits, and the key you called with. |
GET /v1/account/usage?days=30 | Calls, errors and credits per UTC day (1–90 days) and your top endpoints. output=csv gives the daily rows. |
GET /v1/account/logs | Your calls of the last 30 days, newest first. Filters: status (ok, error or a code), route (prefix), key, since; next page with before. output=csv|ndjson downloads up to 5,000 rows per request (next cursor in x-next-cursor). |
curl "https://api.api.sh/v1/account" -H "x-api-key: $APISH_KEY" Fetch a past response again
Every response can be downloaded again for 30 days (Enterprise teams choose their own retention). GET /v1/results/{request_id} returns the exact response of an earlier call (its x-request-id) again, for free, so a crashed script never has to pay twice. It works with output=csv|ndjson too, and appears a few seconds after the call finishes. Older calls answer 410. Your logs (and their CSV / NDJSON export in the dashboard) cover the same 30 days.
curl "https://api.api.sh/v1/results/1c30702c-083c-424e-b836-e5fecafd6166" -H "x-api-key: $APISH_KEY" Spend limits
Set a daily and a monthly limit in credits under Billing (or with the MCP tool set_spend_limits). A call that would take today's or this month's spend (UTC) past a limit is refused with 402 and "spend_limit": "daily" or "monthly", is not charged, and says when the limit resets. Limits apply within about a minute, and very bursty traffic can pass a limit by a few calls. We email you at 50, 80 and 100% of the monthly limit and at 90% of the daily one. To limit one key rather than the whole team, give it a monthly credit cap.
OpenAPI and Postman
The whole API, with every parameter and an example response per endpoint, as an OpenAPI 3.1 file (for code generators, API clients and AI tools) and a Postman collection (import it and set the apiKey variable). Both update with every release; see the changelog. Need just one site? Each platform has its own small OpenAPI file at api.sh/openapi/<platform>.json, for example Reddit, which code generators and AI agents handle more easily than the whole API.
Use it from an AI assistant
The API.SH MCP server lets Claude, Cursor and other MCP clients search the catalog, call endpoints, read your logs and manage keys.
Teams, security and more
- Teams and roles: share credits, keys and billing; invite people with the right role.
- Account security: two-factor login, required 2FA and verified domains.
- Request an API: send a page or a whole site and we'll build it.
- Enterprise: single sign-on, SCIM, network allow-lists, audit export and invoicing.