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

# Sponsors

> Search for brands that recently sponsored media channels/publications.

Provide exactly one scope filter: `categories` or `publication_url`.

- `categories`: Find sponsors active in those content verticals.
- `publication_url`: Find sponsors for a specific creator/publication.

Use `platforms`, date range, and confidence parameters to refine results.

Use this endpoint to find brands that have sponsored creators. Each result
groups the matching placements under one sponsor name and includes summary
counts plus the most recent placement.

A sponsor can appear in more than one result when its name is spelled
differently. Those results can share a `sponsor_id`; when it is present, use
that ID to identify the same sponsor across name variants.

The most recent placement includes `monetization_type`, `disclosure_tier`,
and the legacy `sponsor_type` label. To see every sponsored post, use
[List sponsorships](/sponsorships/sponsorships). See [Sponsorship
types](/sponsorships/types) for field definitions and differences between
Instagram and TikTok labels.

To poll for newly detected sponsor activity without repeatedly loading the
same history, see [Fetch new sponsor activity](/sponsorships/activity-windows).


## OpenAPI

````yaml get /v1/sponsors
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/sponsors:
    get:
      tags:
        - Sponsorships
      summary: Sponsors
      description: >-
        Search for brands that recently sponsored media channels/publications.


        Provide exactly one scope filter: `categories` or `publication_url`.


        - `categories`: Find sponsors active in those content verticals.

        - `publication_url`: Find sponsors for a specific creator/publication.


        Use `platforms`, date range, and confidence parameters to refine
        results.
      operationId: sponsors
      parameters:
        - name: categories
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
                maxItems: 3
              - type: 'null'
            description: >-
              Content-vertical phrases or keywords (e.g. 'consumer tech',
              'startup tools', 'personal finance'). Not brand or company names.
              Free-form strings are normalized to our standard category taxonomy
              and used to scope the search. Mutually exclusive with
              publication_url.
            examples:
              - - consumer tech
                - startup tools
            title: Categories
          description: >-
            Content-vertical phrases or keywords (e.g. 'consumer tech', 'startup
            tools', 'personal finance'). Not brand or company names. Free-form
            strings are normalized to our standard category taxonomy and used to
            scope the search. Mutually exclusive with publication_url.
          example:
            - consumer tech
            - startup tools
        - name: publication_url
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              A creator's publication URL (YouTube channel, Substack newsletter,
              podcast, etc.) to find its sponsors. Mutually exclusive with
              categories.
            examples:
              - https://techweekly.substack.com
            title: Publication Url
          description: >-
            A creator's publication URL (YouTube channel, Substack newsletter,
            podcast, etc.) to find its sponsors. Mutually exclusive with
            categories.
        - name: platforms
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Platforms to include when searching for sponsors. If omitted,
              results include all available platforms.
            examples:
              - - substack
                - podcast
            title: Platforms
          description: >-
            Platforms to include when searching for sponsors. If omitted,
            results include all available platforms.
        - name: confidence_threshold
          in: query
          required: false
          schema:
            type: number
            maximum: 1
            minimum: 0
            description: Minimum sponsorship confidence threshold
            default: 0.5
            title: Confidence Threshold
          description: Minimum sponsorship confidence threshold
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 50
            minimum: 1
            title: Limit
            description: >-
              Maximum number of results per page. Requesting more than 20
              results requires a credits-based plan.
            default: 20
          description: >-
            Maximum number of results per page. Requesting more than 20 results
            requires a credits-based plan.
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Pagination cursor from next_cursor. To continue an activity
              window, pass it with the same filters and omit activity_after and
              activity_token.
            title: Cursor
          description: >-
            Pagination cursor from next_cursor. To continue an activity window,
            pass it with the same filters and omit activity_after and
            activity_token.
        - name: include_evidence
          in: query
          required: false
          schema:
            type: boolean
            description: >-
              Include structured evidence for the most recent ad (source,
              excerpt, and transcript offset when available)
            default: false
            title: Include Evidence
          description: >-
            Include structured evidence for the most recent ad (source, excerpt,
            and transcript offset when available)
        - name: sponsor_types
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Only return sponsors with a placement whose sponsor_type is one of
              these values. When omitted, defaults to ['explicit_ad',
              'implicit_ad', 'affiliate', 'promotion', 'unknown']. Other valid
              values include: 'merch_store', 'self_promotion'.
            examples:
              - - explicit_ad
                - implicit_ad
                - affiliate
                - promotion
                - unknown
            title: Sponsor Types
          description: >-
            Only return sponsors with a placement whose sponsor_type is one of
            these values. When omitted, defaults to ['explicit_ad',
            'implicit_ad', 'affiliate', 'promotion', 'unknown']. Other valid
            values include: 'merch_store', 'self_promotion'.
        - name: sponsor_type
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            title: Sponsor Type
            description: Alternate name for sponsor_types; accepts one or more values.
          description: Alternate name for sponsor_types; accepts one or more values.
        - name: days_back
          in: query
          required: false
          schema:
            type: integer
            maximum: 365
            minimum: 1
            title: Days Back
            description: Time window in days (default 90). Ignored when since is provided.
            default: 90
          description: Time window in days (default 90). Ignored when since is provided.
        - name: since
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Start date (YYYY-MM-DD, inclusive). Overrides days_back. Required
              when until is provided.
            title: Since
          description: >-
            Start date (YYYY-MM-DD, inclusive). Overrides days_back. Required
            when until is provided.
        - name: until
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              End date (YYYY-MM-DD, inclusive). Defaults to today when only
              since is provided.
            title: Until
          description: >-
            End date (YYYY-MM-DD, inclusive). Defaults to today when only since
            is provided.
        - name: sort_by
          in: query
          required: false
          schema:
            enum:
              - total_ads
              - recent
            type: string
            description: >-
              Sort order for results. 'total_ads' (default) ranks brands by
              number of placements. 'recent' ranks by most recent ad date. For
              activity searches, these rank only placements in the returned
              activity window.
            default: total_ads
            title: Sort By
          description: >-
            Sort order for results. 'total_ads' (default) ranks brands by number
            of placements. 'recent' ranks by most recent ad date. For activity
            searches, these rank only placements in the returned activity
            window.
        - name: activity_after
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Return sponsors with placements first detected after this ISO-8601
              datetime. The response reports the inclusive end as
              activity_window.through. Requires platforms. Values before
              activity tracking began use that start time. Cannot be combined
              with activity_token.
            title: Activity After
          description: >-
            Return sponsors with placements first detected after this ISO-8601
            datetime. The response reports the inclusive end as
            activity_window.through. Requires platforms. Values before activity
            tracking began use that start time. Cannot be combined with
            activity_token.
        - name: activity_token
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Opaque token from the final page of the previous activity window.
              Requires platforms and the same filters as the request that
              produced it. Cannot be combined with activity_after.
            title: Activity Token
          description: >-
            Opaque token from the final page of the previous activity window.
            Requires platforms and the same filters as the request that produced
            it. Cannot be combined with activity_after.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimplifiedPartnerSearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
      x-code-samples:
        - lang: curl
          source: |-
            curl -X GET 'https://api.upriver.ai/v1/sponsors?industry=tech' \
              -H 'X-API-Key: YOUR_API_KEY'
components:
  schemas:
    SimplifiedPartnerSearchResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/SimplifiedPartnerSearchResult'
          type: array
          title: Results
          description: List of partner content results
        total_count:
          type: integer
          title: Total Count
          description: Number of results in the current page (not a grand total)
        industry_category:
          anyOf:
            - type: string
            - type: 'null'
          title: Industry Category
          description: The industry category searched
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
          description: Cursor for fetching the next page of results
        has_more:
          type: boolean
          title: Has More
          description: Whether there are more results available
          default: false
        activity_token:
          anyOf:
            - type: string
            - type: 'null'
          title: Activity Token
          description: >-
            Token returned after the final page of an activity window. Pass it
            as activity_token on the next request with the same filters.
        activity_window:
          anyOf:
            - $ref: '#/components/schemas/ActivityWindow'
            - type: 'null'
          description: >-
            Effective first-detection interval represented by this response.
            Returned only for activity searches.
      type: object
      required:
        - results
        - total_count
      title: SimplifiedPartnerSearchResponse
      description: Response for simplified partner search by industry
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SimplifiedPartnerSearchResult:
      properties:
        partner_name:
          type: string
          title: Partner Name
          description: Name of the partner/sponsor entity
          example: Microsoft
        sponsor_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Sponsor Id
          description: >-
            Canonical identifier for this sponsor. Store it and use it for later
            sponsor-specific searches, saved filters, and deduplication. Results
            on this endpoint remain grouped by sponsor name, so two results may
            share one sponsor_id. It may be null when unavailable.
          example: br_0123456789abcdef
        sponsor_domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Sponsor Domain
          description: Canonical apex domain associated with the sponsor when available
          example: microsoft.com
        sponsor_linkedin_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Sponsor Linkedin Url
          description: LinkedIn company profile URL for the sponsor when available
          example: https://www.linkedin.com/company/microsoft
        sponsor_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Sponsor Description
          description: Brief description of the sponsor brand when available
        total_ads_found:
          type: integer
          title: Total Ads Found
          description: >-
            Total number of sponsored content pieces found across all
            publications
          default: 1
          example: 5
        last_detected_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Last Detected At
          description: >-
            When this sponsor's most recently detected placement in the returned
            activity window was first detected.
        new_placements_in_window:
          anyOf:
            - type: integer
            - type: 'null'
          title: New Placements In Window
          description: >-
            Number of this sponsor's placements first detected in the returned
            activity window.
        most_recent_ad:
          $ref: '#/components/schemas/MostRecentAd'
      type: object
      required:
        - partner_name
        - most_recent_ad
      title: SimplifiedPartnerSearchResult
      description: Partner search result showing aggregated sponsorship data
    ActivityWindow:
      properties:
        after:
          type: string
          format: date-time
          title: After
          description: Exclusive start of the returned activity window.
        through:
          type: string
          format: date-time
          title: Through
          description: Inclusive end of the returned activity window.
      type: object
      required:
        - after
        - through
      title: ActivityWindow
      description: Effective first-detection interval represented by an activity response.
    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
    MostRecentAd:
      properties:
        publication_name:
          type: string
          title: Publication Name
          description: Name of the publication where the ad appeared
          example: TechCrunch
        publication_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Publication Url
          description: URL of the publication
          example: https://techcrunch.com
        publication_categories:
          items:
            type: string
          type: array
          title: Publication Categories
          description: Categories of the publication
          example:
            - technology
            - startups
        publication_platform:
          anyOf:
            - type: string
            - type: 'null'
          title: Publication Platform
          description: Platform of the publication
          example: substack
        content_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Content Url
          description: URL of the specific content containing the ad, if available
          example: https://example.com/article
        sponsor_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Sponsor Type
          description: >-
            Legacy single-label sponsorship category for the most recent ad (for
            example explicit_ad, implicit_ad, affiliate, promotion, or unknown),
            kept for backward compatibility. It groups several available signals
            into one value; for example, explicit_ad does not prove a cash
            payment.
          example: explicit_ad
        monetization_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Monetization Type
          description: >-
            Likely type of deal for the most recent ad: paid_partnership,
            affiliate, gifted, or unknown (some older placements carry
            promotion, self_promotion, or merch_store). It does not confirm a
            private contract or payment. Omitted when it was not populated.
          example: paid_partnership
        disclosure_tier:
          anyOf:
            - type: string
            - type: 'null'
          title: Disclosure Tier
          description: >-
            Strongest evidence found for the most recent ad's creator-sponsor
            relationship: platform_verified, creator_disclosed,
            commercial_signal, or inferred. Omitted when it was not populated.
          example: platform_verified
        published_date:
          anyOf:
            - type: string
            - type: 'null'
          title: Published Date
          description: Date when this ad was published (YYYY-MM-DD)
          example: '2024-03-15'
        evidence:
          anyOf:
            - $ref: '#/components/schemas/AdEvidence'
            - type: 'null'
          description: >-
            Structured evidence for the most recent ad, including source and
            offsets. Returned only when 'include_evidence=true'.
      type: object
      required:
        - publication_name
      title: MostRecentAd
      description: Details from the partner's most recent advertisement
    AdEvidence:
      properties:
        source:
          anyOf:
            - type: string
            - type: 'null'
          title: Source
          description: >-
            Origin of the evidence (e.g., 'transcript', 'description',
            'post_body', 'title').
          example: transcript
        excerpt:
          anyOf:
            - type: string
            - type: 'null'
          title: Excerpt
          description: >-
            Short excerpt around the sponsor mention. May be raw text or HTML
            depending on source.
          example: >-
            ...thanks to Acme for sponsoring today's video--use code GADGET for
            10%...
        offset_seconds:
          anyOf:
            - type: number
            - type: 'null'
          title: Offset Seconds
          description: >-
            Approximate timestamp in seconds when source is 'transcript'. Null
            for sources without timing (e.g., description).
          example: 92.5
        confidence:
          anyOf:
            - type: number
            - type: 'null'
          title: Confidence
          description: >-
            Detection confidence for this specific piece of evidence (0-1), when
            available.
          example: 0.88
      type: object
      title: AdEvidence
      description: Structured evidence about where/how the sponsor was detected.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

````