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

# Keywords Research

> Research high-opportunity keywords for a given domain and topic

Discover keyword opportunities with clustering, search volume, difficulty scores, and intent analysis.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.agenticpencil.com/v1/keywords/research" \
    -H "Authorization: Bearer ap_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "domain": "sonant.ai",
      "topic": "ai receptionist",
      "country": "us",
      "limit": 20
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.agenticpencil.com/v1/keywords/research",
      headers={"Authorization": "Bearer ap_your_api_key_here"},
      json={"domain": "sonant.ai", "topic": "ai receptionist", "country": "us", "limit": 20}
  )
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.agenticpencil.com/v1/keywords/research', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer ap_your_api_key_here', 'Content-Type': 'application/json' },
    body: JSON.stringify({ domain: 'sonant.ai', topic: 'ai receptionist', country: 'us', limit: 20 })
  });
  ```
</RequestExample>

## Authorization

<ParamField header="Authorization" type="string" required>
  Bearer token. Format: `Bearer ap_your_api_key`
</ParamField>

## Request Body

<ParamField body="domain" type="string" required>
  Your website domain (e.g., "example.com")
</ParamField>

<ParamField body="topic" type="string">
  Topic or niche to research keywords for
</ParamField>

<ParamField body="keywords" type="string[]">
  Seed keywords to use instead of topic
</ParamField>

<ParamField body="country" type="string">
  Two-letter country code (default: "us"). Supported: us, uk, ca, au, de, fr, es, it, br, pt, nl, in
</ParamField>

<ParamField body="language" type="string">
  Language code (default: "en"). Supported: en, de, fr, es, it, pt, nl, tr
</ParamField>

<ParamField body="limit" type="integer">
  Maximum keywords per source (default: 50)
</ParamField>

## Response

<ResponseExample>
  ```json Success Response theme={null}
  {
    "success": true,
    "data": {
      "domain": "sonant.ai",
      "topic": "ai receptionist",
      "country": "us",
      "clusters": [
        {
          "cluster_name": "ai receptionist",
          "total_volume": 4500,
          "avg_difficulty": 35,
          "keywords": [
            {
              "keyword": "ai receptionist",
              "search_volume": 2400,
              "keyword_difficulty": 32,
              "cpc": 5.2,
              "search_intent": "commercial"
            }
          ]
        }
      ],
      "total_keywords": 45
    },
    "meta": {
      "credits_used": 5,
      "credits_remaining": 995,
      "request_id": "abc-123"
    }
  }
  ```
</ResponseExample>

<Info>**Credit Cost**: 5 credits per request</Info>