Skip to content
UpriverUpriverUpriver API Docs

Get Breakout Entity

v1.0.0
OpenAPI 3.1.0

Upriver API

A social insights API for ad generation platforms. It provides structured signals, like psychographics, behavioral insights, trends, and audience language, to help AI models generate relevant, higher-converting ads.

Server:https://api.upriver.ai

Production API server

Client Libraries
Shell Curl

Get Breakout Entity

​

Get one entity's current breaking topics and a coarse timeline.

Path Parameters
  • entity_id
    Type: string · Entity Id
    required

    Opaque entity identifier

Query Parameters
  • sort
    Type: string · Sort

    Topic ordering, to match the list view: 'recommended' (default) orders an entity's topics by notability, 'newest' by recency. Pass the same sort you listed with so the expanded topics match the listed rows.

  • temporal_status
    Type: string · Temporal Statusenumnullable

    Restrict this entity's topics to those tied to an event of this timing relative to now: 'upcoming' (not yet started), 'ongoing' (in progress), or 'past'. Only topics tied to a scheduled event have a timing.

    values
    • upcoming
    • ongoing
    • past
Responses
  • application/json
  • application/json
Request Example for get/v1/entities/{entity_id}/breakout
curl 'https://api.upriver.ai/v1/entities/{entity_id}/breakout' \
  --header 'X-API-Key: YOUR_SECRET_TOKEN'

{
  "entity_id": "string",
  "name": "string",
  "entity_type": "string",
  "velocity": 1,
  "trend_direction": "string",
  "last_activity_at": "2026-09-05T06:49:26.587Z",
  "topics": [
    {
      "topic_id": "string",
      "name": "string",
      "citations": [
        {
          "source_category": "string",
          "source_url": "string",
          "title": "string",
          "display": ""
        }
      ],
      "source_summary": {
        "additionalProperty": 1
      },
      "citation_rate": [
        {
          "day": "string",
          "count": 1
        }
      ],
      "last_activity_at": "2026-09-05T06:49:26.587Z"
    }
  ],
  "timeline": [
    {
      "day": "string",
      "topic_count": 1
    }
  ]
}

Successful Response