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

# Get Topics by Reference

> Query all commentaries for an external_reference

Returns all commentaries for a given `external_reference` across all personas. This is the primary endpoint for correlating commentaries back to your content.

## Path Parameters

<ParamField path="ref" type="string" required>
  The external\_reference value provided when creating the topic
</ParamField>

## Response

<ResponseField name="external_reference" type="string">
  The queried external reference
</ResponseField>

<ResponseField name="topic_id" type="string">
  The associated topic ID
</ResponseField>

<ResponseField name="content" type="string">
  The topic content
</ResponseField>

<ResponseField name="metadata" type="object">
  Partner-supplied metadata
</ResponseField>

<ResponseField name="commentaries" type="array">
  Array of commentary results per persona
</ResponseField>

<ResponseField name="summary" type="object">
  Summary counts (total, completed, pending, failed)
</ResponseField>

<RequestExample>
  ```bash theme={null}
  curl https://prod.api.unleeshed.ai/partner/v1/topics/by-reference/bet-line-12345 \
    -H "X-Api-Key: your_api_key"
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "external_reference": "bet-line-12345",
      "topic_id": "abc123-uuid",
      "content": "Dolphins -7 vs. Bears",
      "metadata": {
        "bet_type": "spread",
        "line": -7
      },
      "commentaries": [
        {
          "share_id": "share-uuid-1",
          "persona_id": "persona-uuid-1",
          "persona_name": "Mike Thompson",
          "persona_image": "https://cdn.unleeshed.ai/...",
          "status": "completed",
          "commentary": {
            "id": "commentary-uuid",
            "content": "The Dolphins are looking strong...",
            "audio_url": "https://cdn.unleeshed.ai/audio/...",
            "video_url": null
          },
          "created_at": "2026-02-04T10:00:00Z"
        },
        {
          "share_id": "share-uuid-2",
          "persona_id": "persona-uuid-2",
          "persona_name": "Sarah Chen",
          "persona_image": "https://cdn.unleeshed.ai/...",
          "status": "pending",
          "commentary": null,
          "created_at": "2026-02-04T10:00:00Z"
        }
      ],
      "summary": {
        "total_personas": 2,
        "completed": 1,
        "pending": 1,
        "failed": 0
      }
    }
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 404 theme={null}
  {
    "success": false,
    "error": {
      "code": "not_found",
      "message": "No topics found with external_reference \"bet-line-12345\""
    }
  }
  ```
</ResponseExample>