Researcher API

Create and poll asynchronous Rankability Researcher jobs, understand mode-specific costs 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.

Costs, cache, and failure behavior

Mode	Current non-cached cost
discover	500 credits
trending	750 credits
reddit	750 credits
youtube	750 credits
ecommerce	750 credits

A valid cached result is free and can be reused for up to seven days. It returns HTTP 200, status: "completed", cached: true, and credits_charged: 0.

A fresh job charges at creation and returns HTTP 201, status: "pending", and the mode-specific credits_charged. If the job later fails without usable output, Rankability attempts an idempotent refund. The job detail response exposes credits_refunded for a failed job.

Setting refresh: true deliberately bypasses the cache and can create a new charge. 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 and credits_refunded.

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.

• 402 insufficient_credits — the organization cannot afford fresh research.

• 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 charge or queue the job safely.

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