> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keupera.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Keywords

> Research, enrich, and manage keywords and keyword groups.

Manage keyword research programmatically — list, add, delete, star, bulk-update status, trigger AI-powered research, and organize keywords into groups. Every endpoint below has a live playground in the sidebar.

## What you can do

<CardGroup cols={2}>
  <Card title="Manage keywords" icon="list-check">
    List with filters, add in bulk (with optional enrichment), delete, star, and bulk-update status.
  </Card>

  <Card title="Run AI research" icon="wand-magic-sparkles">
    Expand seed terms into ranked keyword ideas with DataForSEO enrichment.
  </Card>

  <Card title="Organize into groups" icon="folder-tree">
    List keyword groups and assign keywords to them (groups are auto-created on add).
  </Card>

  <Card title="Enrich on demand" icon="database">
    Pass `enrich: true` when adding keywords to auto-fill volume, difficulty, CPC, and intent.
  </Card>
</CardGroup>

## The research job flow

`POST /keywords/research` is a **long-running** operation. It returns a `job_id` immediately with `202 Accepted` — poll `GET /keywords/research/{jobId}` until `status` is `completed` or `failed`.

<Steps>
  <Step title="Start the job">
    `POST /keywords/research` with your `seed_keywords`. You get back `{ "job_id", "status": "pending", "poll_url" }`.
  </Step>

  <Step title="Poll for completion">
    `GET /keywords/research/{jobId}` returns `status` — one of `pending`, `processing`, `completed`, or `failed`. Results land in `result` when done.
  </Step>
</Steps>

<Warning>
  Avoid `sync: true` in production — it waits inline and is subject to gateway timeouts. Keyword research consumes crawl credits and returns `402` when your quota is exhausted.
</Warning>