Researcher: keyword research
Start keyword research jobs, poll them and read saved Researcher projects.
Researcher
Section titled “Researcher”The Researcher endpoints let API clients run keyword research jobs and read saved Researcher projects. They reuse the same job runner, idempotency cache, per-org concurrency limiter, and credit costs as the in-app Researcher tool.
All five Researcher endpoints are live at https://app.rankability.com/api/agent/v1/researcher/*. Requests with a valid rk_live_ API key scoped to researcher:run or researcher:read will receive a proper JSON response — not a 401. A 401 response indicates an invalid, expired, or revoked API key, or a missing Authorization: Bearer rk_live_... header.
Scopes
Section titled “Scopes”researcher:run— Start keyword research jobsresearcher:read— Poll job status, list jobs, list saved projects, fetch project keywords
Credit costs
Section titled “Credit costs”| Mode | Operation | Credits |
|---|---|---|
discover (default) |
keyword_research |
500 |
trending |
keyword_research_trending |
750 |
reddit |
keyword_research_reddit |
750 |
youtube |
keyword_research_youtube |
750 |
ecommerce |
keyword_research_ecommerce |
750 |
| (cache hit) | keyword_research_cached |
0 |
Cache hits are returned synchronously and cost nothing. Non-cached jobs are charged up-front when the job is queued; credits are not refunded on worker failure (matches the rest of the platform’s billable async APIs).
Researcher — Start Job
Section titled “Researcher — Start Job”POST /api/agent/v1/researcher/jobs
Start a keyword research job. If a recent cache entry exists for the same input fingerprint, returns the completed job synchronously.
Scope required: researcher:run
Request body
Section titled “Request body”{ "topics": ["emergency plumber st louis", "24 hour plumber"], "country": "us", "location": "St. Louis, MO", "client_id": "uuid", "business_description": "24/7 plumbing services in the St. Louis metro area", "competitor_domains": ["competitor1.com", "competitor2.com"], "target_audience": "Homeowners with urgent plumbing issues", "content_goals": "Drive emergency service bookings", "include_gsc": false, "use_knowledge_base": false, "mode": "discover", "refresh": false}| Field | Type | Required | Description |
|---|---|---|---|
topics |
string[] | Yes | 1–20 seed topics |
country |
string | No | Two-letter country code (default us) |
location |
string | No | City/region for SERP geo-targeting |
client_id |
UUID | No | Associate with a Client (must belong to your org) |
business_description |
string | No | Free-text business description |
competitor_domains |
string[] | No | Domains to mine for competitor keywords |
target_audience |
string | No | Audience description |
content_goals |
string | No | Goals (educate, convert, etc.) |
include_gsc |
boolean | No | Pull in Google Search Console data when available |
use_knowledge_base |
boolean | No | Pull brand context from the Client’s Knowledge Base. Defaults to true when client_id is provided and the field is omitted — explicit false overrides this. |
mode |
string | No | discover (default), trending, reddit, youtube, ecommerce |
refresh |
boolean | No | Skip cache and re-run from scratch |
Send an Idempotency-Key header to safely retry without double-charging.
Response (201, fresh job)
Section titled “Response (201, fresh job)”{ "job_id": "uuid", "status": "pending", "cached": false, "credits_charged": 500, "mode": "discover", "created_at": "2026-04-24T15:30:00.000Z"}Response (200, cache hit)
Section titled “Response (200, cache hit)”{ "job_id": "uuid", "status": "completed", "cached": true, "cached_at": "2026-04-23T18:12:00.000Z", "credits_charged": 0, "mode": "discover", "created_at": "2026-04-24T15:30:00.000Z"}Errors
Section titled “Errors”400 invalid_input— Missing topics, malformed body, or invalid mode402 insufficient_credits— Not enough credits; response details includerequired,available, andoperation404 not_found—client_iddoes not belong to your organization429 concurrency_limit_reached— Per-org concurrent job limit reached;Retry-Afteris set
Researcher — Poll Job
Section titled “Researcher — Poll Job”GET /api/agent/v1/researcher/jobs/:job_id
Scope required: researcher:read
Response
Section titled “Response”{ "job_id": "uuid", "status": "completed", "progress": { "stage": "complete", "detail": "Found 320 keywords in 12 clusters" }, "client_id": null, "mode": "discover", "topics": ["emergency plumber st louis"], "country": "us", "results": { "totalKeywords": 320, "clusters": [ { "name": "emergency plumber", "keywords": [ { "keyword": "emergency plumber st louis", "volume": 1900, "kd": 42, "cpc": "8.50", "intent": "transactional", "opportunityScore": 78, "trend": [10, 12, 15, 14, 16], "source": "dataforseo" } ] } ] }, "error": null, "credits_refunded": 0, "created_at": "2026-04-24T15:30:00.000Z", "completed_at": "2026-04-24T15:32:11.000Z"}status is one of pending, processing, completed, or failed. results is null until the job completes; error is populated if it fails. Poll every 5–10 seconds.
credits_refunded reports how many credits were returned to your org’s balance for this job. It is 0 for pending/processing/completed jobs and for failed jobs that were never charged (e.g. cache hits or pre-charge validation failures). When a failed job had its charge reversed, the value matches the credits originally deducted. Use it to confirm a refund landed without inspecting your billing transactions.
Researcher — List Jobs
Section titled “Researcher — List Jobs”GET /api/agent/v1/researcher/jobs
Scope required: researcher:read
Query parameters
Section titled “Query parameters”client_id(optional) — Filter to a specific Clientlimit(optional, default 50, max 100)offset(optional)
Response
Section titled “Response”{ "jobs": [ { "job_id": "uuid", "status": "completed", "client_id": null, "mode": "discover", "topics": ["emergency plumber st louis"], "country": "us", "total_keywords": 320, "cluster_count": 12, "created_at": "2026-04-24T15:30:00.000Z", "completed_at": "2026-04-24T15:32:11.000Z" } ], "pagination": { "limit": 50, "offset": 0, "count": 1 }}Full results are not included in the list view — fetch a single job to get them.
Researcher — List Projects
Section titled “Researcher — List Projects”GET /api/agent/v1/researcher/projects
Scope required: researcher:read
Returns saved Researcher projects (manually-curated keyword lists), most recently updated first.
Query parameters
Section titled “Query parameters”client_id(optional)limit(default 50, max 100)offset
Response
Section titled “Response”{ "projects": [ { "id": "uuid", "name": "St. Louis plumber keywords", "description": "Manually-curated emergency service terms", "client_id": null, "country": "us", "keyword_count": 42, "created_at": "2026-04-10T00:00:00.000Z", "updated_at": "2026-04-24T12:00:00.000Z" } ], "pagination": { "limit": 50, "offset": 0, "count": 1 }}Researcher — Get Project
Section titled “Researcher — Get Project”GET /api/agent/v1/researcher/projects/:id
Scope required: researcher:read
Returns the project plus all saved keywords, ordered by most-recently added.
Response
Section titled “Response”{ "id": "uuid", "name": "St. Louis plumber keywords", "description": "Manually-curated emergency service terms", "client_id": null, "country": "us", "keyword_count": 2, "created_at": "2026-04-10T00:00:00.000Z", "updated_at": "2026-04-24T12:00:00.000Z", "keywords": [ { "id": "uuid", "keyword": "emergency plumber st louis", "volume": 1900, "kd": 42, "cpc": "8.50", "intent": "transactional", "opportunity_score": 78, "cluster": "emergency plumber", "trend": [10, 12, 15, 14, 16], "source": "dataforseo", "source_favicon": null, "experimental": false, "position": null, "ranking_url": null, "impressions": null, "clicks": null, "ctr": null, "status": "not_started", "priority": "not_set", "next_action": "no_action", "added_at": "2026-04-10T00:00:00.000Z" } ]}Returns 404 not_found if the project does not belong to your organization.
End-to-end example
Section titled “End-to-end example”# 1. Start a jobcurl -X POST https://app.rankability.com/api/agent/v1/researcher/jobs \ -H "Authorization: Bearer rk_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"topics":["emergency plumber st louis"],"country":"us"}'# => { "job_id": "abc-123", "status": "pending", "credits_charged": 500, ... }
# 2. Poll until completedcurl https://app.rankability.com/api/agent/v1/researcher/jobs/abc-123 \ -H "Authorization: Bearer rk_live_YOUR_KEY"# => { "status": "completed", "results": { ... }, ... }