Researcher API

Create and poll asynchronous Rankability Researcher jobs, understand pooled usage and caching, and read saved keyword projects.

Use the Researcher API to start keyword-research jobs, poll their results, and read projects that have already been saved in Researcher. API jobs and saved projects are related but separate resources.

Scopes and routes

Method	Path	Scope	Purpose
`POST`	`/researcher/jobs`	`researcher:run`	Start a research job
`GET`	`/researcher/jobs`	`researcher:read`	List research jobs
`GET`	`/researcher/jobs/:job_id`	`researcher:read`	Poll a job and read its result
`GET`	`/researcher/projects`	`researcher:read`	List saved Researcher projects
`GET`	`/researcher/projects/:id`	`researcher:read`	Read a saved project and its keywords

Prefix every path with https://app.rankability.com/api/agent/v1.

Start a research job

curl -X POST https://app.rankability.com/api/agent/v1/researcher/jobs \
  -H "Authorization: Bearer rk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: research-acme-2026-08-01" \
  -d '{
    "topics": ["commercial roofing st louis"],
    "country": "us",
    "client_id": "CLIENT_UUID",
    "mode": "discover"
  }'

Request fields

Field	Required	Behavior
`topics`	Yes	Array of 1–20 non-empty seed topics
`country`	No	Two-to-five-character country code; defaults to `us`
`location`	No	More specific geographic context
`client_id`	No	Must belong to the authenticated organization
`business_description`	No	Business context; Rankability derives a fallback from client knowledge or topics
`competitor_domains`	No	Domains used as research context
`target_audience`	No	Audience context
`content_goals`	No	Intended content outcome
`include_gsc`	No	Requests connected Search Console context when available
`use_knowledge_base`	No	Includes client knowledge; defaults to true when `client_id` is supplied and the field is omitted
`mode`	No	`discover`, `trending`, `reddit`, `youtube`, or `ecommerce`; defaults to `discover`
`refresh`	No	Bypasses a valid cached result and starts paid fresh research

Rankability also applies organization and client topic exclusions to the research run.

Usage, cache, and failure behavior

Mode	Current non-cached impact
`discover`	Standard pooled-usage impact
`trending`	Standard pooled-usage impact
`reddit`	Standard pooled-usage impact
`youtube`	Standard pooled-usage impact
`ecommerce`	Standard pooled-usage impact

A valid cached result has no additional pooled-usage impact and can be reused for up to seven days. It returns HTTP 200, status: "completed", cached: true, and usage_impact.level: "none".

A fresh job returns HTTP 201, status: "pending", and usage_impact. If the job later fails without usable output, its pending usage is released.

Setting refresh: true deliberately bypasses the cache and can create new usage. Send a stable Idempotency-Key when retrying the same create request.

Poll the job

curl https://app.rankability.com/api/agent/v1/researcher/jobs/JOB_ID \
  -H "Authorization: Bearer rk_live_YOUR_KEY"

Poll every 5–10 seconds with backoff. Treat these as distinct states:

pending — accepted and waiting to run.
processing — research is running.
completed — results contains the keyword-research payload.
empty — the run completed but filtering produced no usable keywords.
failed — no usable result; inspect error.

The progress.stage and progress.detail fields provide current progress. Do not treat a null results field on an in-progress job as a failed search.

List jobs or saved projects

GET /researcher/jobs accepts client_id, limit, and offset. The list contains summaries, not each job’s complete result.

GET /researcher/projects lists projects saved through Researcher. GET /researcher/projects/:id adds the project’s saved keyword rows, including volume, difficulty, CPC, intent, opportunity score, cluster, rank and GSC fields when available, status, priority, and next action.

Creating an API research job does not automatically create a saved Researcher project. Use the job result unless your workflow separately saves or manages a project through a supported Rankability workflow.

Common failures

400 invalid_input — fields failed validation or job_id is malformed.
429 usage_limit_reached — a pooled on-demand window has reached its current limit.
404 not_found — the client, job, or project is outside the organization or does not exist.
429 rate_limit_exceeded — the API request limit or Researcher concurrency limit was reached.
500 internal_error — the system could not record or queue the job safely.

See API usage, rate limits, and errors before implementing retries. For workflow selection, return to API use cases and integration patterns.