Skip to main content

1. Create an API key

In the dashboard, go to Settings → API Keys and create one. Copy it immediately — the full key is shown once. See Create an API key.

2. Verify it works

A key is bound to one organization, so this returns that one. The id is the orgId for organization-scoped paths.
Only organizations whose membership you’ve accepted are listed. A pending invitation doesn’t appear and doesn’t grant access.

3. List projects

Paginated, so the response carries meta:

4. Everything else is under /v1/projects

This is the part worth internalising: only project list and create are nested under an organization. Every other project resource sits at the top level, with the organization derived from the project:
So reading tracked keywords is:
A project outside your key’s organization answers 404, not 403 — see Errors.

5. Add tracked keywords

location_code 2840 is the United States and language_code en is English. All three market fields are required — there’s no default. Any place and language the engine searches from works, down to a city or postal code: find codes with GET /v1/reference/locations?engine=google&search=austin and GET /v1/reference/languages?engine=google. search_engine is google, bing, yahoo, baidu, naver or seznam. Keywords are lower-cased and de-duplicated, so submitting overlapping lists is safe. The keywords added get a first rank check of their own straight away; positions land within about 20 minutes.

6. Billable calls need an explicit organization

Some endpoints have neither an organization nor a project in the path — live SERP lookups, keyword research, trends, domain data:
These are billed to an organization, so with a user token you must pass org_id as a query parameter. Omitting it returns BAD_REQUEST: “org_id is required. This call is billed to an organization, so it cannot be inferred.” With an API key it’s inferred from the key, and you can omit it.

Handling responses

Always check success:
Don’t test for the presence of data — a successful DELETE returns data: null.

What to expect from the data

Most endpoints return stored data from the last background collection, not a live lookup. Reading rankings returns the last completed check; it doesn’t trigger a new one. Endpoints that start work return a job to poll. See Jobs and polling.

Next