> ## 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. # Sponsorships > Return individual sponsored placements (content-level rows). Provide at least one of `sponsor_name`, `sponsor_id`, `sponsor_channel_id`, `brand_id`, `publication_url`, or `categories`. These can be combined, except `publication_url` and `categories` cannot be used together. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/sponsorships 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/sponsorships: get: tags: - Sponsorships summary: Sponsorships description: >- Return individual sponsored placements (content-level rows). Provide at least one of `sponsor_name`, `sponsor_id`, `sponsor_channel_id`, `brand_id`, `publication_url`, or `categories`. These can be combined, except `publication_url` and `categories` cannot be used together. operationId: sponsorships parameters: - name: brand_id in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Deprecated: use sponsor_id.' deprecated: true title: Brand Id description: 'Deprecated: use sponsor_id.' deprecated: true - name: sponsor_id in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Filter to placements from the sponsor with this identifier. Sponsor identifiers appear in the sponsor_id field of results. title: Sponsor Id description: >- Filter to placements from the sponsor with this identifier. Sponsor identifiers appear in the sponsor_id field of results. - name: sponsor_channel_id in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Filter to placements attributed to this sponsor-owned social account, given as a channel_id from the sponsor channels endpoints. Combine with sponsor_id to intersect the two filters. title: Sponsor Channel Id description: >- Filter to placements attributed to this sponsor-owned social account, given as a channel_id from the sponsor channels endpoints. Combine with sponsor_id to intersect the two filters. - name: brand_name in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Deprecated. Same as sponsor_name - filter placements by sponsor/brand name title: Brand Name description: >- Deprecated. Same as sponsor_name - filter placements by sponsor/brand name example: Notion - name: sponsor_name in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Convenience filter for finding a sponsor by display name. Use the sponsor_id returned in results for later sponsor-specific requests because names can vary. Preferred over deprecated brand_name. title: Sponsor Name description: >- Convenience filter for finding a sponsor by display name. Use the sponsor_id returned in results for later sponsor-specific requests because names can vary. Preferred over deprecated brand_name. - name: publication_url in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Filter placements by a creator's publication URL (YouTube channel, Substack newsletter, podcast, etc.). Cannot be combined with categories. title: Publication Url description: >- Filter placements by a creator's publication URL (YouTube channel, Substack newsletter, podcast, etc.). Cannot be combined with categories. - name: platforms in: query required: false schema: anyOf: - type: array items: type: string enum: - beehiiv - ghost - instagram - newsletter - podcast - substack - tiktok - youtube - type: 'null' description: >- Platforms to include (e.g., substack, podcast, youtube). If omitted, includes all. Repeat platforms to provide multiple values. title: Platforms description: >- Platforms to include (e.g., substack, podcast, youtube). If omitted, includes all. Repeat platforms to provide multiple values. example: - youtube - name: platform in: query required: false schema: anyOf: - type: array items: type: string enum: - beehiiv - ghost - instagram - newsletter - podcast - substack - tiktok - youtube - type: 'null' description: >- Alias for platforms. Prefer platforms; repeat platforms to provide multiple values. title: Platform description: >- Alias for platforms. Prefer platforms; repeat platforms to provide multiple values. - 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'). Not brand or company names. Free-form strings are normalized to our standard category taxonomy and matched against publication categories. Cannot be combined with publication_url. title: Categories description: >- Content-vertical phrases or keywords (e.g. 'consumer tech', 'startup tools'). Not brand or company names. Free-form strings are normalized to our standard category taxonomy and matched against publication categories. Cannot be combined with publication_url. - name: sponsor_types in: query required: false schema: anyOf: - items: type: string type: array - type: 'null' description: >- Only return placements whose sponsor_type is one of these values. Use monetization_type and disclosure_tier to filter by those fields. Defaults to ['explicit_ad', 'implicit_ad', 'affiliate', 'promotion', 'unknown']. title: Sponsor Types description: >- Only return placements whose sponsor_type is one of these values. Use monetization_type and disclosure_tier to filter by those fields. Defaults to ['explicit_ad', 'implicit_ad', 'affiliate', 'promotion', 'unknown']. - name: sponsor_type in: query required: false schema: anyOf: - items: type: string type: array - type: 'null' description: Alternate name for sponsor_types; accepts one or more values. title: Sponsor Type description: Alternate name for sponsor_types; accepts one or more values. - name: monetization_types in: query required: false schema: anyOf: - items: type: string type: array - type: 'null' description: >- Only return placements whose monetization_type is one of these values (paid_partnership, affiliate, gifted, or unknown; some older placements carry promotion, self_promotion, or merch_store). Matches only placements where the field is populated. If omitted, does not filter. title: Monetization Types description: >- Only return placements whose monetization_type is one of these values (paid_partnership, affiliate, gifted, or unknown; some older placements carry promotion, self_promotion, or merch_store). Matches only placements where the field is populated. If omitted, does not filter. - name: monetization_type in: query required: false schema: anyOf: - items: type: string type: array - type: 'null' description: Alternate name for monetization_types; accepts one or more values. title: Monetization Type description: Alternate name for monetization_types; accepts one or more values. - name: disclosure_tiers in: query required: false schema: anyOf: - items: type: string type: array - type: 'null' description: >- Only return placements whose disclosure_tier is one of these values (platform_verified, creator_disclosed, commercial_signal, or inferred). Matches only placements where the field is populated. Requesting inferred includes inferred placements without setting include_inferred. If omitted, does not filter. title: Disclosure Tiers description: >- Only return placements whose disclosure_tier is one of these values (platform_verified, creator_disclosed, commercial_signal, or inferred). Matches only placements where the field is populated. Requesting inferred includes inferred placements without setting include_inferred. If omitted, does not filter. - name: disclosure_tier in: query required: false schema: anyOf: - items: type: string type: array - type: 'null' description: Alternate name for disclosure_tiers; accepts one or more values. title: Disclosure Tier description: Alternate name for disclosure_tiers; accepts one or more values. - name: is_first_party in: query required: false schema: anyOf: - type: boolean - type: 'null' description: >- Filter by counterparty. true returns only placements promoting the creator's own product, service, or store, which are excluded by default. false excludes those placements. If omitted, does not filter. title: Is First Party description: >- Filter by counterparty. true returns only placements promoting the creator's own product, service, or store, which are excluded by default. false excludes those placements. If omitted, does not filter. - name: confidence_threshold in: query required: false schema: type: number maximum: 1 minimum: 0 description: >- Only return placements with at least this sponsorship confidence (0-1). Defaults to 0.5, which excludes lower-confidence matches. default: 0.5 title: Confidence Threshold description: >- Only return placements with at least this sponsorship confidence (0-1). Defaults to 0.5, which excludes lower-confidence matches. - name: days_back in: query required: false schema: type: integer maximum: 365 minimum: 1 description: Time window in days (default 90). Ignored when since is provided. default: 90 title: Days Back 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. example: '2024-04-01' - 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. example: '2024-09-30' - name: activity_after in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Start a sponsorship activity request after this ISO-8601 datetime. Requires platforms. Earlier values use the first supported activity time. For later requests, save next_sync_token from a response and send it as sync_token. title: Activity After description: >- Start a sponsorship activity request after this ISO-8601 datetime. Requires platforms. Earlier values use the first supported activity time. For later requests, save next_sync_token from a response and send it as sync_token. - name: sync_token in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Opaque checkpoint returned as next_sync_token by an earlier activity request. Use it instead of activity_after to start the next request. title: Sync Token description: >- Opaque checkpoint returned as next_sync_token by an earlier activity request. Use it instead of activity_after to start the next request. - name: include_evidence in: query required: false schema: type: boolean description: >- Include structured evidence (source, excerpt, transcript offset) when available. default: false title: Include Evidence description: >- Include structured evidence (source, excerpt, transcript offset) when available. - name: include_inferred in: query required: false schema: type: boolean description: >- Include placements where the sponsorship was inferred rather than explicitly disclosed or verified. These are lower-confidence and are excluded by default. Each result's disclosure_tier and partner_confidence let you filter further. default: false title: Include Inferred description: >- Include placements where the sponsorship was inferred rather than explicitly disclosed or verified. These are lower-confidence and are excluded by default. Each result's disclosure_tier and partner_confidence let you filter further. - name: limit in: query required: false schema: type: integer maximum: 50 minimum: 1 description: >- Maximum number of results per page. Requesting more than 20 results requires a credits-based plan. default: 20 title: Limit 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. To continue a paginated activity request, pass this cursor with the same filters and omit activity_after and sync_token. title: Cursor description: >- Pagination cursor. To continue a paginated activity request, pass this cursor with the same filters and omit activity_after and sync_token. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SponsorshipsResponse' '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/sponsorships?brand_name=Notion&platforms=youtube&since=2024-04-01&until=2024-09-30' \ -H 'X-API-Key: YOUR_API_KEY' components: schemas: SponsorshipsResponse: properties: results: items: $ref: '#/components/schemas/SponsorshipPlacement' type: array title: Results description: >- List of sponsorship placements. Each record connects one sponsor, piece of content, and publication. Coauthored content can appear once for each participating publication. total_count: type: integer title: Total Count description: >- Number of placement records. Coauthored content can count more than once because each participating publication has its own record. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: Cursor for fetching the next page has_more: type: boolean title: Has More description: Whether more results are available default: false next_sync_token: anyOf: - type: string - type: 'null' title: Next Sync Token description: >- Token for starting the next sponsorship activity request. Save it after processing the results from this response that you intend to keep. Returned only for activity searches. tracking_status: anyOf: - $ref: '#/components/schemas/SponsorshipTrackingStatus' - type: 'null' description: Tracking status when publication_url is provided. type: object required: - results - total_count title: SponsorshipsResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError SponsorshipPlacement: properties: sponsor_id: anyOf: - type: string - type: 'null' title: Sponsor Id description: >- Canonical identifier for this sponsor. After finding a sponsor by name or domain, use this identifier for later sponsor-specific searches, saved filters, and deduplication. It may be null when unavailable. example: br_01hzy8k9m4qp7v2wxr3d5abcde sponsor_name: type: string title: Sponsor Name description: Name of the sponsor/brand example: Microsoft sponsor_domain: anyOf: - type: string - type: 'null' title: Sponsor Domain description: Canonical apex domain associated with the sponsor example: microsoft.com sponsor_linkedin_url: anyOf: - type: string - type: 'null' title: Sponsor Linkedin Url description: LinkedIn company profile URL for the sponsor 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 example: >- Microsoft is a global technology company that develops software, cloud services, and hardware. sponsor_type: anyOf: - type: string - type: 'null' title: Sponsor Type description: >- Legacy single-label sponsorship category for this placement (for example explicit_ad, implicit_ad, affiliate, promotion, or unknown), kept for backward compatibility. It groups several sponsorship signals into one value; for example, explicit_ad can also represent gifted content and does not prove a cash payment. Use monetization_type to see the likely deal and disclosure_tier to see the relationship evidence. This field remains available for filtering. example: explicit_ad sponsor_channel_ids: anyOf: - items: type: string format: uuid type: array - type: 'null' title: Sponsor Channel Ids description: >- Sponsor-owned social accounts observed in this placement's evidence, given as channel_id values (the same identifiers the sponsor channels endpoints return). A placement can list zero, one, or several. Absent when no sponsor-owned account was identified for the placement. example: - c0ffee00-0000-0000-0000-000000000000 partner_confidence: anyOf: - type: number - type: 'null' title: Partner Confidence description: >- Best-effort confidence that the creator-sponsor relationship is present (0-1). It is not confidence in a specific compensation mechanism or legal compliance conclusion. example: 0.92 monetization_type: anyOf: - type: string - type: 'null' title: Monetization Type description: >- Likely type of deal: paid_partnership (paid sponsorship), affiliate (commission from attributed actions), gifted (a product, service, access, or experience was provided; cash is not implied), or unknown (the deal type could not be determined). The value is based on available content and platform signals; it does not confirm a private contract or payment. For some older records, it was translated from sponsor_type and can also be promotion, self_promotion, or merch_store. The field is 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 creator-sponsor relationship: platform_verified (platform data identifies the named relationship), creator_disclosed (the creator's content discloses it), commercial_signal (a link, code, or similar cue supports it), or inferred (the context suggests it without a stronger signal). This field describes how the relationship was identified, not the deal type or legal compliance. For some older records, it was translated from sponsor_type. The field is omitted when it was not populated. example: platform_verified is_first_party: anyOf: - type: boolean - type: 'null' title: Is First Party description: >- True when the placement promotes the creator's own product, service, or store; false when a third-party sponsor was identified. Omitted when the counterparty could not be determined. example: false publication_name: type: string title: Publication Name description: Name of the publication where the placement appeared example: Cloud Weekly publication_url: anyOf: - type: string - type: 'null' title: Publication Url description: URL of the publication example: https://cloudweekly.substack.com publication_categories: items: type: string type: array title: Publication Categories description: Categories for the publication example: - technology - cloud publication_platform: anyOf: - type: string - type: 'null' title: Publication Platform description: Platform of the publication (e.g., substack, podcast, youtube) example: substack content_title: anyOf: - type: string - type: 'null' title: Content Title description: Title of the content containing the placement example: K8s cost control tips content_url: anyOf: - type: string - type: 'null' title: Content Url description: Canonical URL of the specific content, if available example: https://cloudweekly.substack.com/p/k8s-cost-control published_date: anyOf: - type: string - type: 'null' title: Published Date description: Publication date (YYYY-MM-DD) example: '2024-08-12' evidence: anyOf: - $ref: '#/components/schemas/AdEvidence' - type: 'null' description: >- Structured evidence for the placement (source, excerpt, transcript offset). type: object required: - sponsor_name - publication_name title: SponsorshipPlacement description: One sponsor, piece of content, and publication. SponsorshipTrackingStatus: properties: publication_url: type: string title: Publication Url description: The YouTube URL that was checked channel_name: anyOf: - type: string - type: 'null' title: Channel Name description: Channel name if known status: type: string title: Status description: '''active'', ''pending'', or ''not_tracked''' message: type: string title: Message description: Human-readable explanation default: '' type: object required: - publication_url - status title: SponsorshipTrackingStatus description: Tracking status for a publication in the sponsorship pipeline. 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 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 ````