The Video Social Listening API

01 Overview

The YBOT Partner Data API serves YBOT's own video social-listening dataset — brand and product mentions that YBOT detects and analyses in publicly available video on YouTube, TikTok and Instagram — as a small set of read-only JSON operations. You receive YBOT's derived insights, not the platforms' data. Your own systems, or an AI agent using the operations as tools, call it directly; nobody has to open a dashboard.

Everything lives under /v1, takes and returns JSON, and is gated by an API key with the data:search scope. Output is always aggregated and allowlisted: personal data — names, verbatim quotes, birth dates — is never returned.

02 Quickstart

Three steps to your first competitive share-of-voice result.

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

03 Authentication

Send your key in the X-API-Key header on every request. Keys carry a scope and a plan; the plan sets a fixed-window rate limit and a monthly request quota. A missing or unscoped key is rejected before any query runs.

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

Some keys are access_level: "raw" (larger search result sets); most are aggregate (examples capped at 10).

04 Data model

Three indices back every operation. You filter, group and rank over their declared fields; a query naming a field outside the allowlist is rejected. Output is always a redacted subset.

Filter kinds: term (exact), range (numeric {gte,lte}), date_range ({gte,lte} ISO dates). Metrics combine a type — count · sum · avg · min · max — with a metric field.

05 aggregate

The core "open question" primitive: group an index by a dimension and rank the buckets by a metric. "Which creators talk most about retinol?" → group siv_business_ideas by channel_name, filter components: "retinol", count.

curl -X POST https://partners.yourbrandontime.com/v1/aggregate \
  -H "X-API-Key: pk_live_your_key_here" -H "Content-Type: application/json" \
  -d '{ "index":"siv_business_ideas", "group_by":"channel_name",
       "filters":{ "components":"retinol" },
       "metric":{ "type":"avg", "field":"sentiment_score" }, "size":10 }'

→ { "matched_documents":1284, "buckets":[
     { "key":"Hyram", "count":61, "metric":0.42, "metric_type":"avg:sentiment_score" } ] }

06 search

Example documents — allowlisted fields only, capped at 10 unless your key is access_level: "raw". q is full-text over the index's free-text fields (e.g. siv_info title/description).

07 creators

A convenience wrapper over search on siv_content_creator: ranked creators with aggregate audience demographics. Filter by niche, geography or size; sort by any creator metric.

Returns creator profiles with subscriber_count, engagement_rate_viewers and aggregate viewer_age_distribution / viewer_gender_distribution / viewer_country_distribution.

08 co-mentions

Find videos or channels that mention all of the given brands together — the co-occurrence primitive behind "who talks about A and B". Returns IDs + counts only (an aggregation), never raw documents.

curl -X POST https://partners.yourbrandontime.com/v1/co-mentions \
  -H "X-API-Key: pk_live_your_key_here" -H "Content-Type: application/json" \
  -d '{ "values":["Nike","IKEA"], "group_by":"video_id" }'

→ { "results":[ { "key":"vid_88", "total_mentions":7, "matched_values":2 } ] }

09 sector · Share of Voice

Rank a competitive set of brands by how present each is in video against the rest, month by month — volume, reach, sentiment and topics. This is the endpoint behind the sector Share-of-Voice report.

{ "brands":[ {
    "label":"Repsol", "coverage":"ok", "low_confidence":false,
    "totals":{ "unique_videos":760, "views":26900000 },
    "series":[ { "month":"2026-01",
      "unique_videos":152,   // 1 per video
      "mentions":158,        // every mention (100 in one video = 100)
      "views":8673694, "sentiment":0.061,
      "volume_sov":76.38,     // % share by unique videos
      "reach_sov":97.27,      // % share by views
      "top_topics":[ { "topic":"energy", "count":50 } ] } ] } ],
  "meta":{ "from":"2026-01-01", "to":"2026-06-30",
    "caps":{ "max_brands":30, "video_cap":3000, "low_coverage":20 } } }

10 schema

A machine-readable description of every operation, the queryable indices, their fields and allowed values — so the API is self-documenting at runtime and an agent can use the operations as tools without hard-coding the contract.

11 Using the API from an AI agent

The API is deliberately agent-friendly: a handful of typed, read-only operations with strict guardrails and a machine-readable contract. The intended wiring — the same pattern Epsilon's DAI uses — is:

{
  "name": "sector_share_of_voice",
  "description": "Rank a set of brands by share of voice in video (volume, reach, sentiment, topics) over a date window.",
  "input_schema": {
    "type": "object",
    "properties": {
      "brands": { "type": "array", "maxItems": 30,
        "items": { "type": "object", "required": ["label","terms"] } },
      "from_date": { "type": "string", "format": "date" },
      "to_date":   { "type": "string", "format": "date" }
    },
    "required": ["brands","from_date","to_date"]
  }
}  // tool handler = POST /v1/sector with the tool input as the JSON body

12 Recipes

Common questions and the call that answers each.

13 Glossary

Share of Voice (SoV)

A brand's presence as a percentage of the tracked set over a period. Reported two ways: by volume and by reach.

Volume SoV

Share measured by unique videos — one video counts once, however many times the brand appears in it.

Reach SoV

Share measured by views — weights each mention by how many people could have seen it.

Mention vs. unique video

A mention counts every occurrence (100 in one video = 100); a unique_video counts the video once.

Sentiment score

Average tone of the mentions, from −1 (negative) to +1 (positive).

Co-mention

Two or more brands appearing together in the same video or channel — a signal of comparison, collab or competitive framing.

Coverage

low when a brand has too few videos for its percentages to be statistically reliable.

Topic

An LLM-extracted theme attached to a mention (e.g. energy, oil-and-gas), with a frequency count.

14 Frequently asked questions

15 Errors

Errors are JSON with a human-readable message. Guardrail violations name the exact field to fix.

16 Limits & quota

Data is computed and stored in the EU (Scaleway) — no US cloud in the path. The API returns aggregates and allowlisted fields only; raw personal data never leaves.