API reference

Base URL https://partners.yourbrandontime.com · auth headerX-API-Key. The authoritative list of fields, dimensions and metrics is always live at /v1/schema.

Indices

siv_business_ideas — brand/product mentions from spoken transcripts (sentiment, brands, components/ingredients, topics, opportunities). The main analytics index.

Every brand mention has a mention_scope: product (products, services, marketing, customer experience, reputation), financial (the company's stock, investing, earnings, valuation) or corporate (M&A, layoffs, leadership, governance, restructuring, tariffs). Filter "mention_scope": "product" (one value or a list) to keep stock talk out of brand sentiment, or group by it to see how much of the conversation is about the stock. Mentions not classified yet count as product.

siv_content_creator — creator profiles: audience size, engagement, niche, and aggregate audience demographics.

siv_info — video catalogue metadata (title, channel, platform, views, likes, duration, tags).

GET /v1/schema

Returns indices, filterable fields, group-by dimensions, numeric metrics and limits. No body.

curl -s https://partners.yourbrandontime.com/v1/schema -H "X-API-Key: YOUR_API_KEY"

POST /v1/aggregate

Group by a dimension, rank by a metric. The main analytics endpoint.

Body fields: index (required), group_by (required, a whitelisted dimension), metric (required, {type, field?}), filters (optional, exact-match map), order (desc|asc), size (buckets, max 50).

metric.type: count · sum · avg · min · max. Non-count requires metric.field (a numeric field, e.g. sentiment_score, views, subscriber_count).

curl -s -X POST https://partners.yourbrandontime.com/v1/aggregate \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"index":"siv_business_ideas","filters":{"category":"Beauty"},
       "group_by":"brand_name","metric":{"type":"avg","field":"sentiment_score"},
       "order":"desc","size":10}'

Response: { status, result:[{ data:{ index, group_by, matched_documents, buckets:[{key,count,metric?}] } }] }

POST /v1/search

Example documents with allowlisted fields only (no personal data). Body: index, filters (exact-match), q (optional full-text, only on siv_info), size (capped — 10 for aggregate keys, up to 50 for raw), sort_field/sort_order (optional, numeric/date fields). For bulk or ongoing delivery use /v1/sync.

curl -s -X POST https://partners.yourbrandontime.com/v1/search \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"index":"siv_info","filters":{"platform":"youtube"},"q":"nike","size":5}'

POST /v1/sync

Incremental delivery for integrations that keep their own copy of the data: documents from siv_business_ideas in processing order (when we extracted them, not the video's upload date), oldest first, with a next_cursor. Requires a raw key.

Body: filters (same exact-match map as search — several brands, sentiment, channels, dates…), size (default 100, max 500), cursor (the previous page's next_cursor), stream (a name for a position we keep for your account), since (YYYY-MM-DD or ISO datetime where a read without cursor starts), reset (forget the stream position and start again).

curl -s -X POST https://partners.yourbrandontime.com/v1/sync \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"stream":"main-feed","filters":{"brand_name":["Nike","Adidas"]},
       "since":"2026-09-01","size":500}'

Response: { result:[{ data:{ returned, has_more, next_cursor, up_to, results:[{ video_id, brand_name, sentiment, processed_at, … }] } }] }. With a stream you don't need to keep the cursor: call again and you only get what is new since your last page (the position survives key rotation). To read a page again, send its cursor. has_more: true means call again now; false means you are up to date.

Documents appear about 5 minutes after processing. When a video is analysed again its results come back as new documents, so replace a video's results by video_id instead of appending them. A cursor or stream is tied to its filters: to change them, use a new stream name or reset: true.

POST /v1/creators

Rank/search creators (siv_content_creator) with metrics and aggregate demographics. Body: filters, sort_field (default subscriber_count), sort_order, size.

curl -s -X POST https://partners.yourbrandontime.com/v1/creators \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"filters":{"dominant_country":"ES"},"sort_field":"subscriber_count","size":10}'

POST /v1/co-mentions

Find the videos or channels that mention all of N values together — e.g. two brands, or a brand + an ingredient. Returns only IDs + counts (it is an aggregation, never raw documents), so it is available to every key.

Body: index (default siv_business_ideas), field (a term field, default brand_name), values (required, list of 2–5), group_by (video_id for same-video, or channel_name/channel_uid for same-creator), size (max 50).

curl -s -X POST https://partners.yourbrandontime.com/v1/co-mentions \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"index":"siv_business_ideas","field":"brand_name",
       "values":["Nike","Adidas"],"group_by":"video_id","size":10}'

Response: { result:[{ data:{ field, values, group_by, results:[{key, total_mentions, matched_values}] } }] }. An empty results means no entity mentions all values together — a valid answer. Resolve a returned video_id to a title with /v1/search on siv_info.

POST /v1/sector

Share of voice for a tracked set of up to 30 brands over a date window of up to 24 months: mentions, reach and sentiment per brand. Body: brands (list of {label, terms, must_context?, exact?}), from_date and to_date (YYYY-MM-DD), optional mention_scopes (e.g. ["product"], so stock talk does not inflate a listed company's share). A video that mentions two brands counts for both, so shares need not add up to 100%.

curl -s -X POST https://partners.yourbrandontime.com/v1/sector \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"brands":[{"label":"Nike","terms":["Nike"]},{"label":"Adidas","terms":["Adidas"]}],
       "from_date":"2026-01-01","to_date":"2026-09-30"}'

POST /v1/sector-suggestions takes the same body and returns other brands often mentioned alongside the set that share its topics — candidates you can decide to add.

Errors & limits

401 missing key · 403 invalid/revoked/insufficient scope · 429 rate limit exceeded · 400 bad request (unknown index/field, or a limit violation) · 503 data backend unavailable.

Two throttles return 429: a per-minute burst cap (anti-abuse) and your plan's monthly call quota (resets each calendar month — shared across all your keys). Both are shown on your Profile › API keys page; upgrade your plan for a higher monthly quota.

Hard caps: size ≤ 50 results per search (500 per /v1/sync page, raw keys), aggregation buckets ≤ 50, query timeout 5s. Personal data (creator real names, exact quotes, individual-level fields) is always redacted; demographics are aggregate distributions only.