Skip to content

Researcher: keyword research

Start keyword research jobs, poll them and read saved Researcher projects.

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.

  • researcher:run — Start keyword research jobs
  • researcher:read — Poll job status, list jobs, list saved projects, fetch project keywords
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).

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

{
"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.

{
"job_id": "uuid",
"status": "pending",
"cached": false,
"credits_charged": 500,
"mode": "discover",
"created_at": "2026-04-24T15:30:00.000Z"
}
{
"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"
}
  • 400 invalid_input — Missing topics, malformed body, or invalid mode
  • 402 insufficient_credits — Not enough credits; response details include required, available, and operation
  • 404 not_found — client_id does not belong to your organization
  • 429 concurrency_limit_reached — Per-org concurrent job limit reached; Retry-After is set

GET /api/agent/v1/researcher/jobs/:job_id

Scope required: researcher:read

{
"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.

GET /api/agent/v1/researcher/jobs

Scope required: researcher:read

  • client_id (optional) — Filter to a specific Client
  • limit (optional, default 50, max 100)
  • offset (optional)
{
"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.

GET /api/agent/v1/researcher/projects

Scope required: researcher:read

Returns saved Researcher projects (manually-curated keyword lists), most recently updated first.

  • client_id (optional)
  • limit (default 50, max 100)
  • offset
{
"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 }
}

GET /api/agent/v1/researcher/projects/:id

Scope required: researcher:read

Returns the project plus all saved keywords, ordered by most-recently added.

{
"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.

Terminal window
# 1. Start a 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" \
-d '{"topics":["emergency plumber st louis"],"country":"us"}'
# => { "job_id": "abc-123", "status": "pending", "credits_charged": 500, ... }
# 2. Poll until completed
curl https://app.rankability.com/api/agent/v1/researcher/jobs/abc-123 \
-H "Authorization: Bearer rk_live_YOUR_KEY"
# => { "status": "completed", "results": { ... }, ... }