apicheats.dev elevenlabs/llms.txt Raw .md
GET

/v1/convai/agents/{agent_id}/topics

ElevenLabs API

Get Agent Conversation Topics

Base URL
https://api.elevenlabs.io
Auth
xi-api-key: <ELEVENLABS_API_KEY>
Last verified
2026-09-03 · upstream hash matched
Actions
Agents: curl -H "Accept: text/markdown" this URL
→ 225 tokens · Vary: Accept

Critical gotchas

Authentication uses the non-standard xi-api-key header, not Authorization: Bearer. Sending a Bearer token returns HTTP 401.

Text-to-speech responses are raw binary audio, not JSON. Write the body to a file (--output speech.mp3) rather than parsing it.

cURL

curl -X GET 'https://api.elevenlabs.io/v1/convai/agents/agent-id/topics?page_size=10&sort_by=conversations&sort_direction=asc&from_unix_secs=10&to_unix_secs=10&include_evaluation_criteria=true&cursor=example-cursor' \  -H "xi-api-key: $ELEVENLABS_API_KEY"
Get a free ElevenLabs API key → sponsored

Parameters

Name In Type Required Description
agent_id path string Yes ID of the agent
page_size query integer No Number of top-level topic groups to return.
sort_by query string No Column to rank topics by. Use conversations for volume, sentiment with sort_direction=asc for the most negative topics, and frustration with sort_direction=desc for the most frustrated ones. Topics with no score are always ranked last.
sort_direction query string No Direction to sort topics.
from_unix_secs query integer No Start of the window to view topics for. When set with to_unix_secs, the completed daily topic-discovery runs in the range are aggregated together, so the window scopes the metrics as well as the topic set. Floored to the start of its UTC day because runs cover whole UTC days; aggregated_run_count reports how many runs were summed. Omit both bounds to get the single latest run.
to_unix_secs query integer No End of the window to view topics for.
include_evaluation_criteria query boolean No Include the per-criteria evaluation breakdown on each topic's metrics. Pass false to drop it: it dominates the payload and the weighted success_rate is returned either way.
cursor query string No Used for fetching next page. Cursor is returned in the response.

Response 200 OK

{
  "topics": [
    {
      "topic_id": "string",
      "label": "string",
      "description": "string",
      "conversation_count": 0,
      "parent_topic_id": "string",
      "x_2d": 0,
      "y_2d": 0,
      "metrics": {
        "conversation_count": 0,
        "sentiment": {
          "sentiment": {
            "count": "[recursive or deeply nested schema]",
            "sum": "[recursive or deeply nested schema]",
            "min": "[recursive or deeply nested schema]",
            "max": "[recursive or deeply nested schema]"
          },
          "frustration": {
            "count": "[recursive or deeply nested schema]",
            "sum": "[recursive or deeply nested schema]",
            "min": "[recursive or deeply nested schema]",
            "max": "[recursive or deeply nested schema]"
          },
          "positive_count": 0,
          "neutral_count": 0,
          "negative_count": 0
        },
        "evaluation_criteria": [
          {
            "criteria_id": "[recursive or deeply nested schema]",
            "success_count": "[recursive or deeply nested schema]",
            "failure_count": "[recursive or deeply nested schema]",
            "unknown_count": "[recursive or deeply nested schema]"
          }
        ]
      },
      "success_rate": 0
    }
  ],
  "window_start_unix_secs": 0,
  "window_end_unix_secs": 0,
  "aggregated_run_count": 0,
  "has_more": false,
  "next_cursor": "string"
}