> ## 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.

# Get Private Breakout Feed



## OpenAPI

````yaml /api-reference/openapi.json get /v1/breakout/feeds/{feed_slug}
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/breakout/feeds/{feed_slug}:
    get:
      tags:
        - Breakout Feeds
      summary: Get Private Breakout Feed
      operationId: get_private_breakout_feed
      parameters:
        - name: feed_slug
          in: path
          required: true
          schema:
            type: string
            title: Feed Slug
        - name: facet
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Facet
        - name: kind
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - evidence
                  - story
                  - theme
                  - trend
                  - entity
                type: string
              - type: 'null'
            title: Kind
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            default: 60
            title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateFeedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    PrivateFeedResponse:
      properties:
        feed:
          $ref: '#/components/schemas/PrivateFeedSummary'
        generated_at:
          type: string
          format: date-time
          title: Generated At
        lookback_days:
          type: integer
          title: Lookback Days
        items:
          items:
            $ref: '#/components/schemas/PrivateFeedItem'
          type: array
          title: Items
      type: object
      required:
        - feed
        - generated_at
        - lookback_days
        - items
      title: PrivateFeedResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PrivateFeedSummary:
      properties:
        slug:
          type: string
          title: Slug
          description: Stable private-feed identifier.
        label:
          type: string
          title: Label
          description: Human-readable private-feed label.
        facets:
          items:
            $ref: '#/components/schemas/PrivateFeedFacet'
          type: array
          title: Facets
          description: Available feed facets.
      type: object
      required:
        - slug
        - label
        - facets
      title: PrivateFeedSummary
    PrivateFeedItem:
      properties:
        item_id:
          type: string
          title: Item Id
        item_type:
          $ref: '#/components/schemas/FormationProjectionItemType'
        facet:
          type: string
          title: Facet
        facet_label:
          type: string
          title: Facet Label
        headline:
          type: string
          title: Headline
        why_relevant:
          type: string
          title: Why Relevant
        why_now:
          type: string
          title: Why Now
        overall_rank:
          anyOf:
            - type: integer
            - type: 'null'
          title: Overall Rank
        facet_rank:
          type: integer
          title: Facet Rank
        evidence_summary:
          $ref: '#/components/schemas/PrivateFeedEvidenceSummary'
        evidence:
          anyOf:
            - $ref: '#/components/schemas/PrivateFeedEvidence'
            - type: 'null'
        formation:
          anyOf:
            - $ref: '#/components/schemas/PrivateFeedFormation'
            - type: 'null'
      type: object
      required:
        - item_id
        - item_type
        - facet
        - facet_label
        - headline
        - why_relevant
        - why_now
        - facet_rank
        - evidence_summary
      title: PrivateFeedItem
    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
    PrivateFeedFacet:
      properties:
        slug:
          type: string
          title: Slug
          description: Stable feed facet identifier.
        label:
          type: string
          title: Label
          description: Human-readable facet label.
      type: object
      required:
        - slug
        - label
      title: PrivateFeedFacet
    FormationProjectionItemType:
      type: string
      enum:
        - evidence
        - formation
      title: FormationProjectionItemType
      description: Whether a projection row points at evidence or a formation.
    PrivateFeedEvidenceSummary:
      properties:
        total:
          type: integer
          title: Total
        shown:
          type: integer
          title: Shown
        source_type_count:
          type: integer
          title: Source Type Count
        latest_shown_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Latest Shown At
      type: object
      required:
        - total
        - shown
        - source_type_count
      title: PrivateFeedEvidenceSummary
    PrivateFeedEvidence:
      properties:
        evidence_id:
          type: string
          title: Evidence Id
          description: Stable source evidence identifier.
        source_type:
          type: string
          title: Source Type
          description: Kind of source containing the evidence.
        source_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Url
          description: Link to the evidence.
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
          description: Evidence title when present.
        excerpt:
          anyOf:
            - type: string
            - type: 'null'
          title: Excerpt
          description: Short evidence excerpt.
        author_handle:
          anyOf:
            - type: string
            - type: 'null'
          title: Author Handle
          description: Public author handle when present.
        community:
          anyOf:
            - type: string
            - type: 'null'
          title: Community
          description: Community containing the evidence.
        published_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Published At
          description: When the evidence was published.
      type: object
      required:
        - evidence_id
        - source_type
      title: PrivateFeedEvidence
    PrivateFeedFormation:
      properties:
        formation_id:
          type: string
          title: Formation Id
        kind:
          $ref: '#/components/schemas/FormationKind'
        identity_state:
          $ref: '#/components/schemas/FormationIdentityState'
        title:
          type: string
          title: Title
        summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Summary
        entities:
          items:
            type: string
          type: array
          title: Entities
        first_seen:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: First Seen
        last_seen:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Last Seen
        evidence:
          items:
            $ref: '#/components/schemas/PrivateFeedEvidence'
          type: array
          title: Evidence
        observations:
          items:
            $ref: '#/components/schemas/PrivateFeedObservation'
          type: array
          title: Observations
      type: object
      required:
        - formation_id
        - kind
        - identity_state
        - title
        - entities
        - evidence
        - observations
      title: PrivateFeedFormation
    FormationKind:
      type: string
      enum:
        - story
        - theme
        - trend
        - entity
      title: FormationKind
      description: What an observed formation represents.
    FormationIdentityState:
      type: string
      enum:
        - provisional
        - canonical
      title: FormationIdentityState
      description: Whether identity is still run-local or maintained across observations.
    PrivateFeedObservation:
      properties:
        observed_at:
          type: string
          format: date-time
          title: Observed At
          description: When this measurement was made.
        evidence_count:
          type: integer
          title: Evidence Count
          description: Evidence count at this observation.
        source_type_count:
          type: integer
          title: Source Type Count
          description: Distinct source-type count.
        momentum_ratio:
          anyOf:
            - type: number
            - type: 'null'
          title: Momentum Ratio
          description: Recent activity relative to its baseline.
        trajectory:
          type: string
          title: Trajectory
          description: Observed direction of activity.
      type: object
      required:
        - observed_at
        - evidence_count
        - source_type_count
        - trajectory
      title: PrivateFeedObservation
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

````