---
title: "Researcher: keyword research"
description: "Start keyword research jobs, poll them and read saved Researcher projects."
canonical_url: "https://developers.rankability.com/guides/researcher"
section: "Guides"
last_updated: 2026-11-14
---

# Researcher: keyword research

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

## 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

- `researcher:run` — Start keyword research jobs
- `researcher:read` — Poll job status, list jobs, list saved projects, fetch project keywords

### 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

`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

```json
{
  "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)

```json
{
  "job_id": "uuid",
  "status": "pending",
  "cached": false,
  "credits_charged": 500,
  "mode": "discover",
  "created_at": "2026-04-24T15:30:00.000Z"
}
```

### Response (200, cache hit)

```json
{
  "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

- `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

## Researcher — Poll Job

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

**Scope required**: `researcher:read`

### Response

```json
{
  "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

`GET /api/agent/v1/researcher/jobs`

**Scope required**: `researcher:read`

### Query parameters

- `client_id` (optional) — Filter to a specific Client
- `limit` (optional, default 50, max 100)
- `offset` (optional)

### Response

```json
{
  "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

`GET /api/agent/v1/researcher/projects`

**Scope required**: `researcher:read`

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

### Query parameters

- `client_id` (optional)
- `limit` (default 50, max 100)
- `offset`

### Response

```json
{
  "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

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

**Scope required**: `researcher:read`

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

### Response

```json
{
  "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

```bash
# 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": { ... }, ... }
```
