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",
      "content_url": "https://cloudweekly.substack.com/p/k8s-cost-control",
      "sponsor_domain": "microsoft.com",
      "sponsor_linkedin_url": "https://www.linkedin.com/company/microsoft",
      "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",
      "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
}

Authorizations

​
X-API-Key
string
header
required

Query Parameters

​
brand_id
string | null

Filter placements by brand/entity id (preferred)

​
brand_name
string | null

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

​
sponsor_name
string | null

Filter placements by sponsor/brand name

​
publication_url
string | null

Filter placements by publication URL

​
platforms
string[] | null

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

​
categories
string[] | null

Category phrases or keywords used to limit placements. Free-form strings are normalized to our standard category taxonomy and matched against publication categories.

​
sponsor_types
string[] | null

Filter by sponsorship types (e.g., explicit_ad, promotion, affiliate, unknown). Defaults to ['explicit_ad', '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 (ignored if since/until provided)

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

Start date (YYYY-MM-DD). If provided, overrides days_back

​
until
string | null

End date (YYYY-MM-DD). Optional; defaults to today if omitted.

​
include_evidence
boolean
default:false

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

​
top_k_categories
integer
default:3

When resolving 'categories', number of category matches to consider per phrase

Required range: 1 <= x <= 10
​
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