Skip to main content
GET
/
partner
/
v1
/
topics
/
{id}
/
status
curl -X GET "https://prod.api.unleeshed.ai/partner/v1/topics/abc123/status" \
  -H "X-Api-Key: pk_live_your_api_key"

{
  "success": true,
  "data": {
    "topic_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "content": "Should the Lakers trade Anthony Davis?",
    "overall_status": "partial",
    "created_at": "2026-01-30T12:00:00Z",
    "personas": [
      {
        "persona_id": "pers_abc123",
        "persona_name": "Coach Mike",
        "status": "creator_approved",
        "status_updated_at": "2026-01-30T14:30:00Z",
        "has_commentary": true
      },
      {
        "persona_id": "pers_xyz789",
        "persona_name": "Analytics Amy",
        "status": "commentary_generated",
        "status_updated_at": "2026-01-30T14:15:00Z",
        "has_commentary": false
      },
      {
        "persona_id": "pers_def456",
        "persona_name": "Hot Take Harry",
        "status": "topic_sent",
        "status_updated_at": "2026-01-30T12:00:00Z",
        "has_commentary": false
      }
    ],
    "summary": {
      "total": 3,
      "topic_sent": 1,
      "opinion_injected": 0,
      "commentary_generated": 1,
      "creator_approved": 1,
      "declined": 0,
      "expired": 0
    }
  }
}

​
Overview

A lightweight endpoint for checking the workflow status of each persona’s commentary generation. Use this for polling without fetching full commentary content.
This endpoint returns less data than GET /topics/:id, making it ideal for frequent polling.

​
Path Parameters

​
id
string
required
The topic ID returned from POST /topics.

​
Response

​
topic_id
string
The topic identifier.
​
content
string
The topic content.
​
overall_status
string
Aggregated status across all personas:
  • pending - Waiting for creators to respond
  • in_progress - At least one creator is working on commentary
  • partial - Some commentaries ready, others still in progress
  • completed - All commentaries ready to fetch
​
personas
array
Per-persona workflow status:
FieldTypeDescription
persona_idstringPersona UUID
persona_namestringDisplay name
statusstringCurrent workflow stage (see below)
status_updated_atdatetimeWhen status last changed
has_commentarybooleanTrue if ready to fetch
​
summary
object
Count of personas at each stage:
  • total - Total personas
  • topic_sent - Waiting for creator
  • opinion_injected - Creator added perspective, AI generating
  • commentary_generated - Awaiting creator approval
  • creator_approved - Ready to fetch
  • declined - Creator declined
  • expired - Creator didn’t respond in time

​
Workflow Status Values

The status field for each persona follows this progression:
StatusDescriptionHas Commentary
topic_sentWaiting for creator to respondNo
opinion_injectedCreator added perspective, AI generatingNo
commentary_generatedAI finished, awaiting creator approvalNo
creator_approvedReady to fetchYes
declinedCreator declined this topicNo
expiredCreator didn’t respond in time windowNo
curl -X GET "https://prod.api.unleeshed.ai/partner/v1/topics/abc123/status" \
  -H "X-Api-Key: pk_live_your_api_key"

{
  "success": true,
  "data": {
    "topic_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "content": "Should the Lakers trade Anthony Davis?",
    "overall_status": "partial",
    "created_at": "2026-01-30T12:00:00Z",
    "personas": [
      {
        "persona_id": "pers_abc123",
        "persona_name": "Coach Mike",
        "status": "creator_approved",
        "status_updated_at": "2026-01-30T14:30:00Z",
        "has_commentary": true
      },
      {
        "persona_id": "pers_xyz789",
        "persona_name": "Analytics Amy",
        "status": "commentary_generated",
        "status_updated_at": "2026-01-30T14:15:00Z",
        "has_commentary": false
      },
      {
        "persona_id": "pers_def456",
        "persona_name": "Hot Take Harry",
        "status": "topic_sent",
        "status_updated_at": "2026-01-30T12:00:00Z",
        "has_commentary": false
      }
    ],
    "summary": {
      "total": 3,
      "topic_sent": 1,
      "opinion_injected": 0,
      "commentary_generated": 1,
      "creator_approved": 1,
      "declined": 0,
      "expired": 0
    }
  }
}

​
Polling Best Practices

When overall_status is partial, some commentaries are ready. You can fetch and display these while waiting for others.
if (data.overall_status === 'partial' || data.overall_status === 'completed') {
  const commentaries = await fetchCommentaries(topicId);
  displayCommentaries(commentaries);
}
Unlike instant AI APIs, this workflow involves human review. Set your timeout to 24-48 hours rather than minutes.
const MAX_WAIT_HOURS = 24;
const created = new Date(data.created_at);
const elapsed = Date.now() - created.getTime();

if (elapsed > MAX_WAIT_HOURS * 60 * 60 * 1000) {
  // Handle timeout - some creators may not respond
}

Get Commentaries

Fetch ready commentaries when status is creator_approved.

Generate Commentary Guide

Complete integration guide.