Skip to content
UpriverUpriverUpriver API Docs

Get Private Breakout Feed

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 Private Breakout Feed

​
Path Parameters
  • feed_slug
    Type: string · Feed Slug
    required
Query Parameters
  • facet
    Type: string · Facetnullable
  • kind
    Type: string · Kindenumnullable
    values
    • evidence
    • story
    • theme
    • trend
    • entity
  • earliest_evidence_at_or_after
    Type: string · Earliest Evidence At Or AfterFormat: date-timenullable

    Inclusive ISO 8601 lower bound for the result's earliest_evidence_at. Use it to restrict results to activity that first appeared within a recent window. Results with earlier dated evidence, or with no dated evidence, are excluded as a whole; evidence returned within a matching result is not time-filtered. The comparison uses all known supporting evidence, including records omitted by response filters or limits.

  • limit
    Type: integer · Limit
    min:  
    1
    max:  
    100

    Integer numbers.

Responses
  • application/json
  • application/json
Request Example for get/v1/breakout/feeds/{feed_slug}
curl 'https://api.upriver.ai/v1/breakout/feeds/{feed_slug}' \
  --header 'X-API-Key: YOUR_SECRET_TOKEN'

{
  "feed": {
    "slug": "string",
    "label": "string",
    "facets": [
      {
        "slug": "string",
        "label": "string"
      }
    ],
    "presentation_source": "curated",
    "breakout_vertical": "string"
  },
  "generated_at": "2026-09-05T06:49:26.587Z",
  "lookback_days": 1,
  "items": [
    {
      "item_id": "string",
      "parent_item_id": "string",
      "item_type": "evidence",
      "facet": "string",
      "facet_label": "string",
      "headline": "string",
      "why_relevant": "string",
      "why_now": "string",
      "overall_rank": 1,
      "facet_rank": 1,
      "earliest_evidence_at": "2026-09-05T06:49:26.587Z",
      "evidence_summary": {
        "total": 1,
        "shown": 1,
        "source_type_count": 1,
        "latest_shown_at": "2026-09-05T06:49:26.587Z"
      },
      "evidence": {
        "evidence_id": "string",
        "source_type": "string",
        "source_url": "string",
        "title": "string",
        "excerpt": "string",
        "author_handle": "string",
        "community": "string",
        "published_at": "2026-09-05T06:49:26.587Z",
        "claims": [
          {
            "quantity": "string",
            "subject": "string"
          }
        ]
      },
      "formation": {
        "formation_id": "string",
        "kind": "story",
        "identity_state": "provisional",
        "title": "string",
        "summary": "string",
        "maturity": "watchlist",
        "entities": [
          "string"
        ],
        "first_seen": "2026-09-05T06:49:26.587Z",
        "last_seen": "2026-09-05T06:49:26.587Z",
        "evidence": [
          {
            "evidence_id": "string",
            "source_type": "string",
            "source_url": "string",
            "title": "string",
            "excerpt": "string",
            "author_handle": "string",
            "community": "string",
            "published_at": "2026-09-05T06:49:26.587Z",
            "claims": [
              {
                "quantity": "string",
                "subject": "string"
              }
            ]
          }
        ],
        "observations": [
          {
            "observed_at": "2026-09-05T06:49:26.587Z",
            "evidence_count": 1,
            "source_type_count": 1,
            "momentum_ratio": 1,
            "trajectory": "string"
          }
        ]
      }
    }
  ]
}

Successful Response