Skip to main content
GET
/
v1
/
sponsorships
cURL
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'
{
  "results": [
    {
      "sponsor_name": "Microsoft",
      "publication_name": "Cloud Weekly",
      "sponsor_domain": "microsoft.com",
      "sponsor_linkedin_url": "https://www.linkedin.com/company/microsoft",
      "sponsor_description": "Microsoft is a global technology company that develops software, cloud services, and hardware.",
      "match_type": "exact",
      "similarity_score": 0.87,
      "sponsor_type": "explicit_ad",
      "partner_confidence": 0.92,
      "publication_url": "https://cloudweekly.substack.com",
      "publication_categories": [
        "technology",
        "cloud"
      ],
      "publication_platform": "substack",
      "content_title": "K8s cost control tips",
      "content_url": "https://cloudweekly.substack.com/p/k8s-cost-control",
      "published_date": "2024-08-12",
      "evidence": {
        "source": "transcript",
        "excerpt": "...thanks to Acme for sponsoring today's video--use code GADGET for 10%...",
        "offset_seconds": 92.5,
        "confidence": 0.88
      }
    }
  ],
  "total_count": 123,
  "next_cursor": "<string>",
  "has_more": false,
  "tracking_status": {
    "publication_url": "<string>",
    "status": "<string>",
    "channel_name": "<string>",
    "message": ""
  }
}

Authorizations

​
X-API-Key
string
header
required

Query Parameters

​
brand_id
string | null

Filter placements by internal brand/entity id. Not returned by the API; prefer sponsor_name.

​
brand_name
string | null

Deprecated. Same as sponsor_name - filter placements by sponsor/brand name

​
sponsor_name
string | null

Filter placements by sponsor/brand display name (e.g. 'Clay', 'Notion'). Preferred over deprecated brand_name.

​
publication_url
string | null

Filter placements by a creator's publication URL (YouTube channel, Substack newsletter, podcast, etc.). Cannot be combined with categories.

​
platforms
string[] | null

Platforms to include (e.g., substack, podcast, youtube). If omitted, includes all.

​
categories
string[] | null

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.

​
sponsor_types
string[] | null

Filter by sponsorship types (e.g., explicit_ad, promotion, affiliate, unknown). Defaults to ['explicit_ad', 'implicit_ad', 'affiliate', 'promotion', 'unknown'].

​
sponsor_type
string[] | null

Alias for sponsor_types; accepts a single value or repeated values.

​
confidence_threshold
number
default:0.5
Required range: 0 <= x <= 1
​
days_back
integer
default:90

Time window in days (default 90). Ignored when since is provided.

Required range: 1 <= x <= 365
​
since
string | null

Start date (YYYY-MM-DD, inclusive). Overrides days_back. Required when until is provided.

​
until
string | null

End date (YYYY-MM-DD, inclusive). Defaults to today when only since is provided.

​
include_evidence
boolean
default:false

Include structured evidence (source, excerpt, transcript offset) when available.

​
limit
integer
default:20

Maximum number of results per page. Requesting more than 20 results requires a credits-based plan.

Required range: 1 <= x <= 50
​
cursor
string | null

Pagination cursor

Response

Successful Response

​
results
SponsorshipPlacement · object[]
required

List of individual ad placements

​
total_count
integer
required

Total number of placements returned

​
next_cursor
string | null

Cursor for fetching the next page

​
has_more
boolean
default:false

Whether more results are available

​
tracking_status
SponsorshipTrackingStatus · object

Tracking status when publication_url is provided.