Docs · API v1
Documentation
Everything you need to make your first call and run it in production. Per-endpoint parameters are on each API page, and the full OpenAPI file works with Postman and code generators.
Quick start
Create an account, verify your email, and create a key in your dashboard. Then call any endpoint:
curl "https://api.perceptlayer.com/v1/99acres/city-listings?city=mumbai" \
-H "X-API-Key: $API_KEY"Authentication
Send your key in the X-API-Key header. Tools that can't set headers can pass it as the api_key query parameter instead. Keys start with sk_live_, are shown once when you create them, and can be rotated or revoked in the dashboard at any time.
Requests
Every endpoint lives at https://api.perceptlayer.com/v1/{api}/{endpoint}. GET endpoints take parameters in the query string; list parameters repeat, as in ?ids[]=1&ids[]=2. POST endpoints take a JSON body. Unknown parameters are ignored, and invalid ones are rejected before anything is charged.
Responses
Successful calls return the data as JSON with no wrapper. Metadata travels in headers:
X-Request-Id | Unique ID for the call. Quote it when you contact support. |
X-Credits-Used | Credits this call cost. Always 0 for errors. |
X-Credits-Remaining | Your balance after the call. |
Credits
A successful call costs the credits shown on its endpoint, one for nearly all of them. Calls that fail cost nothing. New accounts get 1,000 credits after verifying their email, topped back up each month until the first purchase. See pricing for credit packs.
Errors
Errors use HTTP status codes and a JSON body: {"error": {"code", "message", "request_id"}}.
| Status | Code | Meaning |
|---|---|---|
| 401 | invalid_api_key | Missing, unknown or revoked API key. |
| 402 | insufficient_credits | Your credit balance is used up. Buy more credits to continue. |
| 403 | restricted_endpoint | This endpoint requires accepting the restricted-endpoint terms in your dashboard. |
| 404 | unknown_endpoint | No such endpoint. See the API reference for available endpoints. |
| 404 | not_found | No data was found for these parameters. You were not charged. |
| 410 | endpoint_retired | This endpoint has been retired. |
| 422 | invalid_parameters | The request parameters are invalid. |
| 429 | rate_limited | Too many requests. Retry after the number of seconds in the Retry-After header. |
| 502 | source_error | The data source returned an error. You were not charged. |
| 503 | temporarily_unavailable | The data source is busy. Retry after the number of seconds in the Retry-After header. You were not charged. |
| 504 | timeout | The data source did not answer within 60 seconds. You were not charged. |
Rate limits
Free accounts can make 60 requests a minute per key; accounts that have bought credits get 600. Over the limit you get a 429 with a Retry-After header. Some sources are slower than others, so allow up to 60 seconds per call.
Restricted endpoints
Endpoints that return social, personal or SEO data are marked on their pages. They return 403 restricted_endpoint until you accept the restricted-endpoint terms in your dashboard.
AI agents (MCP)
Agents can use the whole catalogue through our MCP server at https://api.perceptlayer.com/mcp (Streamable HTTP). It has three tools:
search_endpoints | Finds endpoints for a site or kind of data, such as “airbnb listing”. Free. |
get_endpoint | Lists one endpoint's parameters, with an example and its credit cost. Free. |
call_endpoint | Runs an endpoint and returns its JSON. Needs your key, and costs the same credits as an API call. |
Send your key as Authorization: Bearer sk_live_…. In Claude Code:
claude mcp add --transport http perceptlayer https://api.perceptlayer.com/mcp \
--header "Authorization: Bearer $API_KEY"Other clients that support remote MCP servers need the same URL and header. Calls through MCP follow the same rules as the API: failed calls are free, rate limits apply, and restricted endpoints need the terms. Responses longer than 100,000 characters are cut short, so use an endpoint's paging or limit parameters for large results. Connect from a desktop app, a command-line tool or your own server; MCP clients that run in a web browser aren't supported yet.