> ## Documentation Index > Fetch the complete documentation index at: https://docs.upriver.ai/llms.txt > Use this file to discover all available pages before exploring further. # List Breakout Entities > List breaking entities (players or teams) for a vertical. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/entities/breakout openapi: 3.1.0 info: title: Upriver API description: >- 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. version: 1.0.0 servers: - url: https://api.upriver.ai description: Production API server security: [] tags: - name: Brands - name: Products - name: Creators - name: Audience - name: Sponsorships - name: Trends - name: Breakout Topics - name: Taxonomy paths: /v1/entities/breakout: get: tags: - Breakout Topics summary: List Breakout Entities description: List breaking entities (players or teams) for a vertical. operationId: list_breakout_entities parameters: - name: entity_type in: query required: true schema: type: string description: 'Entity kind to rank: ''player'' or ''team''' title: Entity Type description: 'Entity kind to rank: ''player'' or ''team''' - name: sort in: query required: false schema: type: string description: >- Ranking mode: 'recommended' (default, balanced), 'rising' (biggest movers vs own baseline), 'top' (highest absolute volume), or 'newest' (most recently appeared). Legacy aliases (blended, hot, momentum, emerging, importance, recent, new) are accepted. default: recommended title: Sort description: >- Ranking mode: 'recommended' (default, balanced), 'rising' (biggest movers vs own baseline), 'top' (highest absolute volume), or 'newest' (most recently appeared). Legacy aliases (blended, hot, momentum, emerging, importance, recent, new) are accepted. - name: vertical in: query required: false schema: type: string description: Vertical; only 'sports' default: sports title: Vertical description: Vertical; only 'sports' - name: tag in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Filter to entities carrying this tag (e.g. a sport). Use a tag value from the /entities/breakout/tags endpoint. title: Tag description: >- Filter to entities carrying this tag (e.g. a sport). Use a tag value from the /entities/breakout/tags endpoint. - name: temporal_status in: query required: false schema: anyOf: - $ref: '#/components/schemas/TemporalStatusFilter' - type: 'null' description: >- Filter to entities with an event that has this timing relative to now: 'upcoming' (not yet started), 'ongoing' (in progress), or 'past'. Only entities tied to a scheduled event have a timing, so this narrows results to them and to their matching events. title: Temporal Status description: >- Filter to entities with an event that has this timing relative to now: 'upcoming' (not yet started), 'ongoing' (in progress), or 'past'. Only entities tied to a scheduled event have a timing, so this narrows results to them and to their matching events. - name: event in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Filter to entities involved in a specific event, by name (e.g. 'world cup'). An unrecognized event returns no entities. title: Event description: >- Filter to entities involved in a specific event, by name (e.g. 'world cup'). An unrecognized event returns no entities. - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Max entities default: 20 title: Limit description: Max entities - name: offset in: query required: false schema: type: integer minimum: 0 description: Pagination offset default: 0 title: Offset description: Pagination offset - name: discovered_within_hours in: query required: false schema: anyOf: - type: integer maximum: 8760 minimum: 1 - type: 'null' description: >- Only entities whose most recently appeared topic was first seen within this many hours (the 'brand new' filter). Omit for no limit. title: Discovered Within Hours description: >- Only entities whose most recently appeared topic was first seen within this many hours (the 'brand new' filter). Omit for no limit. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/EntityBreakoutListResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: TemporalStatusFilter: type: string enum: - upcoming - ongoing - past title: TemporalStatusFilter description: >- Filter a topic by its request-time event temporal status. Only topics linked to a scheduled event carry a temporal status, so filtering by any of these values implicitly restricts results to event-linked topics. EntityBreakoutListResponse: properties: entities: items: $ref: '#/components/schemas/EntityBreakoutResponse' type: array title: Entities description: Ranked breaking entities total_count: type: integer title: Total Count description: Total matching entities before pagination type: object required: - total_count title: EntityBreakoutListResponse description: Ranked breaking entities for a vertical. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError EntityBreakoutResponse: properties: entity_id: type: string title: Entity Id description: >- Opaque identifier for this entity; reuse with the entity detail endpoint name: type: string title: Name description: Entity display name entity_type: type: string title: Entity Type description: 'Entity kind: ''player'' or ''team''' score: type: number title: Score description: Breakout ranking score (0-1); higher is more notable right now velocity: type: number title: Velocity description: >- Recent activity relative to the entity's own typical level (e.g. 2.4 means 240% above its baseline) trend_direction: type: string title: Trend Direction description: '''rising'', ''steady'', or ''cooling''' last_activity_at: anyOf: - type: string format: date-time - type: 'null' title: Last Activity At description: >- When this entity most recently appeared in breaking coverage (ISO 8601, UTC). top_topics: items: $ref: '#/components/schemas/EntityTopicRef' type: array title: Top Topics description: The entity's current breaking topics type: object required: - entity_id - name - entity_type - score - velocity - trend_direction title: EntityBreakoutResponse description: A breaking entity (player or team) with its supporting topics. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError EntityTopicRef: properties: topic_id: type: string title: Topic Id description: Topic identifier; reuse with the breakout topic endpoints name: type: string title: Name description: Topic name citations: items: $ref: '#/components/schemas/EntityTopicCitation' type: array title: Citations description: A few supporting sources for this topic source_summary: additionalProperties: type: integer type: object title: Source Summary description: 'Supporting-source count by category: {news: 5, reddit: 12, web: 3}' citation_rate: items: $ref: '#/components/schemas/CitationRateBucket' type: array title: Citation Rate description: Daily supporting-source counts for this topic, oldest first last_activity_at: anyOf: - type: string format: date-time - type: 'null' title: Last Activity At description: >- When this topic most recently appeared in breaking coverage (ISO 8601, UTC) type: object required: - topic_id - name title: EntityTopicRef description: A topic the entity is currently breaking in. EntityTopicCitation: properties: source_category: type: string title: Source Category description: 'Source category: news, web, reddit, tiktok, trends' source_url: type: string title: Source Url description: URL of the source title: anyOf: - type: string - type: 'null' title: Title description: Headline of the source, when it has one (null for posts) display: type: string title: Display description: >- Display-ready label for the source — its headline, or the post text when the source has no headline. Prefer this over title. default: '' type: object required: - source_category - source_url title: EntityTopicCitation description: >- A supporting source for a topic — the lean entity-card citation shape. Inherits the shared citation fields (source_category, source_url, title, display) and intentionally adds nothing else; the entity cards only render a compact source link, not the full citation detail. CitationRateBucket: properties: day: type: string title: Day description: Date in YYYY-MM-DD format count: type: integer title: Count description: Number of citations published that day type: object required: - day - count title: CitationRateBucket description: A single day's citation count for charting. securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key ````