The API playground

In shortThe API playground (Content → Developer API → API playground) sends real requests to the AI Rank Lab REST API using your own key and secret, so you can see exactly what a script would get back. Free data endpoints answer at once; paid tools return a job ID that the playground polls until the result is ready. Paid calls spend real credits. Copy as cURL turns any request into a command you can run elsewhere.

What the playground is for

Before you write code against an API you want to see three things: which parameters an endpoint takes, what the response looks like, and how long it takes. The playground shows all three without any setup. It isn't a sandbox: it uses your real key, the real rate limit and your real credit balance, so a paid call here is a paid call.

Before you start

• Your key and secret are loaded automatically. If the banner says Unable to load your API key, open API keys once and come back.
• For domain-based endpoints (bot stats, citations), the domain must be in your own account. Shared domains don't work through the API.
• Connect GA4 or Search Console in the dashboard first if you want to try their endpoints.

Make your first calls

1. Open the playgroundGo to Content → Developer API → API playground. A green banner confirms Authenticated with your API key and shows its first characters. The header has links to API docs, the Postman collection and Manage keys.
2. Start with a free endpointUnder Data endpoints · free, pick Get credit balance and click Send request. The Response card shows the status code, how long it took, how many requests you have left this minute, and the JSON body.
3. Fill in parametersPick another endpoint, for example AI engine citations. Each field is marked required or optional with a description. Domain fields suggest the domains in your account. List fields take comma-separated values.
4. Run a paid toolUnder Tools · async · billed, pick a tool such as SEO + AEO + GEO audit. An amber notice states the price: Sending charges ... credits from your balance. If the job fails, credits are refunded automatically. There's no second confirmation, so check the parameters, then click Send request.
5. Watch the jobThe response is 202 with a jobId. The Job result card polls every 4 seconds and shows the status: pending, processing, then completed or failed. Use Poll now to check at once or Stop to stop polling. A failed job shows that its credits were refunded.
6. Copy as cURLCopy as cURL copies the request as a terminal command with both headers filled in. The preview on screen masks the secret, but the copied text contains the real one, so don't paste it into a ticket or chat.

How async jobs work in your own code

Paid tools don't make you wait on one long request. The pattern is the same for every tool:

1. POST /api/v1/<tool> with a JSON body. Credits are charged and you get 202 with jobId, status: pending, creditsCharged and a pollUrl.
2. GET /api/v1/jobs/<jobId> every few seconds (free) until status is completed or failed.
3. Read result on success. On failure, error explains why and creditsRefunded is true.
4. Jobs and their results are kept for 7 days. Save what you need.

What things cost

Reads of your own data are free: credit balance, bot stats, citations, domains, prompts, job polling, and your connected GA4 and Search Console. Tools cost about what they cost in the dashboard, and each endpoint shows its price in the list. Two differences to know: Core Web Vitals over the API is priced per call rather than as in the dashboard, and REST keyword research is a flat price per job, while the same tool over MCP is metered per data lookup.