Query Responses

curl --request POST \
  --url https://api.athenahq.ai/api/v1/responses \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "website_id": "123e4567-e89b-12d3-a456-426614174000",
  "filters": {
    "start_date": "2024-01-01T00:00:00.000Z",
    "end_date": "2024-12-31T23:59:59.999Z",
    "models": [
      "chatgpt",
      "perplexity"
    ],
    "prompt_ids": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "competitor_ids": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "prompt_status": "active",
    "prompt_type": "branded"
  },
  "page_num": 0,
  "page_size": 40
}
'

{
  "responses": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "website_id": "123e4567-e89b-12d3-a456-426614174000",
      "prompt_id": "123e4567-e89b-12d3-a456-426614174000",
      "base_prompt": "What is the best CRM software?",
      "prompt": "What is the best CRM software for small businesses?",
      "model": "chatgpt",
      "response": "Here are some top CRM options...",
      "mentioned": true,
      "cited": true,
      "created_at": "2024-06-15T10:30:00.000Z",
      "sources": [
        {
          "url": "example.com/article",
          "root_domain": "example.com",
          "normalized_url": "example.com/article",
          "suffix": ".com"
        }
      ],
      "competitors": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "Competitor Inc",
          "url": "competitor.com",
          "position": 1
        }
      ],
      "position": 2
    }
  ]
}

POST

api

responses

Query Responses

curl --request POST \
  --url https://api.athenahq.ai/api/v1/responses \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "website_id": "123e4567-e89b-12d3-a456-426614174000",
  "filters": {
    "start_date": "2024-01-01T00:00:00.000Z",
    "end_date": "2024-12-31T23:59:59.999Z",
    "models": [
      "chatgpt",
      "perplexity"
    ],
    "prompt_ids": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "competitor_ids": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "prompt_status": "active",
    "prompt_type": "branded"
  },
  "page_num": 0,
  "page_size": 40
}
'

{
  "responses": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "website_id": "123e4567-e89b-12d3-a456-426614174000",
      "prompt_id": "123e4567-e89b-12d3-a456-426614174000",
      "base_prompt": "What is the best CRM software?",
      "prompt": "What is the best CRM software for small businesses?",
      "model": "chatgpt",
      "response": "Here are some top CRM options...",
      "mentioned": true,
      "cited": true,
      "created_at": "2024-06-15T10:30:00.000Z",
      "sources": [
        {
          "url": "example.com/article",
          "root_domain": "example.com",
          "normalized_url": "example.com/article",
          "suffix": ".com"
        }
      ],
      "competitors": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "Competitor Inc",
          "url": "competitor.com",
          "position": 1
        }
      ],
      "position": 2
    }
  ]
}

Authorizations

x-api-key

string

header

required

API key for authentication. You can create one here.

Body

application/json

Request body for querying responses

website_id

string<uuid>

required

The ID of the website to query responses for

Example:

"123e4567-e89b-12d3-a456-426614174000"

filters

object

required

Filters for querying responses

Show child attributes

filters.start_date

string<date-time>

required

Filter start date (UTC)

Example:

"2024-01-01T00:00:00.000Z"

filters.end_date

string<date-time>

Filter end date (UTC)

Example:

"2024-12-31T23:59:59.999Z"

filters.models

enum<string>[]

Filter by AI models

Available options:

chatgpt,

perplexity,

gemini,

google_ai_overview,

copilot,

claude,

ai_mode,

grok,

deepseek

Example:

["chatgpt", "perplexity"]

filters.prompt_ids

string<uuid>[]

Filter by specific prompt IDs

filters.competitor_ids

string<uuid>[]

Filter by specific competitor IDs

filters.prompt_status

enum<string>

Filter by prompt status

Available options:

active,

paused

filters.prompt_type

enum<string>

Filter by prompt type

Available options:

branded,

non_branded

page_num

integer

default:0

Page number for pagination (0-indexed)

Required range: x >= 0

Example:

0

page_size

integer

default:40

Number of responses per page

Required range: 1 <= x <= 100

Example:

40

Response

Successful response with list of responses

responses

object[]

required

Show child attributes

responses.id

string<uuid>

required

Unique identifier for the response

Example:

"123e4567-e89b-12d3-a456-426614174000"

responses.website_id

string<uuid>

required

Associated website ID

Example:

"123e4567-e89b-12d3-a456-426614174000"

responses.prompt_id

string<uuid>

required

Associated prompt ID

Example:

"123e4567-e89b-12d3-a456-426614174000"

responses.base_prompt

string

required

Original prompt text

Example:

"What is the best CRM software?"

responses.prompt

string

required

Actual prompt variation used

Example:

"What is the best CRM software for small businesses?"

responses.model

string

required

AI model that generated the response

Example:

"chatgpt"

responses.response

string

required

The AI-generated response text

Example:

"Here are some top CRM options..."

responses.mentioned

boolean

required

Whether your website was mentioned in the response

Example:

true

responses.cited

boolean

required

Whether your website was cited as a source

Example:

true

responses.created_at

string<date-time>

required

Timestamp when the response was captured (UTC)

Example:

"2024-06-15T10:30:00.000Z"

responses.sources

object[]

required

Sources cited in the response

Show child attributes

responses.sources.url

string

required

The source URL

Example:

"example.com/article"

responses.sources.root_domain

string

required

Root domain of the source

Example:

"example.com"

responses.sources.normalized_url

string | null

Normalized version of the URL

Example:

"example.com/article"

responses.sources.suffix

string | null

Domain suffix

Example:

".com"

responses.competitors

object[]

required

Competitors mentioned in the response

Show child attributes

responses.competitors.id

string<uuid>

required

Competitor ID

Example:

"123e4567-e89b-12d3-a456-426614174000"

responses.competitors.name

string

required

Competitor name

Example:

"Competitor Inc"

responses.competitors.url

string

required

Competitor URL

Example:

"competitor.com"

responses.competitors.position

integer

required

Position/rank of competitor mention in the response

Example:

1

responses.position

integer | null

Your website's rank/position in the response (null if not mentioned)

Example:

2

Get Date Range Cumulative Share of Voice

⌘I

Overview

Integrations

Basics

Metrics

Query Responses

Authorizations

Body

Response