Skip to main content
Match is the centre of the API. Give it a video you’ve ingested and it returns a ranked shortlist of licensed tracks, best first. Every other video workflow takes a track_id from here.

​
Match an analyzed video

200
track_id is the Soundstripe song id, and audio_id is the Soundstripe audio-file id. Both are repeated under their explicit soundstripe_* names so there is no guessing which catalog they belong to. Resolve them in your catalog, or pass track_id straight to sync or loop.

​
The three ways this call succeeds

A 200 is the warm path above. The other two are both 202, and they carry different bodies. Branch on which keys are present rather than assuming a job. A video that failed to ingest answers 422 instead, and should be re-submitted.

​
The video is not analyzed yet

Cue analyzes each video under one engine per account, warmed at ingest. When that analysis is not cached for your video, the match runs as a job so it can’t trip the gateway timeout:
202
Poll GET /v1/match/jobs/{job_id} until status is complete. The finished job returns video_id, job_id, status and the same lane as a synchronous match. Polling is free, and the match is billed once, on completion. This is the branch a video hits right after it first turns ready. See the note in the quickstart.

​
The video is still being ingested

If the video’s own ingest hasn’t finished, you get a 202 with no job_id, pointing at the video rather than at a match job:
202
Poll GET /v1/videos/{video_id} until status is ready, then call /v1/match again.

​
Ingest first, match many times

Analysis is the expensive step and it happens once. POST /v1/videos analyzes a clip and returns a video_id, and every match, sync and loop against that video afterwards reuses it. See the quickstart for the ingest call. You can also skip the two-step and pass a video_url directly to /v1/match. Cue starts the ingest and hands you the video, not a match job:
202
There is no job_id on this path and nothing to poll at /v1/match/jobs/. Poll the video, then call /v1/match with the video_id and handle whichever of the three answers above comes back.

​
Steering the shortlist

​
integer
default:"20"
Maximum number of tracks to return, 1–100. The lane is planned as a curated shortlist of up to 10, so asking for more than that returns everything there is rather than more. Asking for fewer returns exactly that many.
​
string
A plain-language brief, e.g. “warm, cinematic, no vocals”. Up to 500 characters.
​
string
A single mood, e.g. “uplifting” or “tense”.
​
string
A period steer, e.g. ”80s”.
​
string
Whether you want vocals, and what kind.
​
boolean
default:"true"
Weight matches toward the tempo Cue detected in the video. Turn it off when the cut rate shouldn’t drive the tempo.

​
Sync points inline

Add "include_sync": true and every track in the response carries two extra fields, sync_status and sync_points. It’s included in the match price, and it’s off by default so the plain call stays lean.
Embedded sync reads the cache and never builds it. A track whose sync profile isn’t indexed yet comes back "sync_status": "warming" with "sync_points": []. On a video you just ingested that is most of the shortlist, so plan for an empty array on the first call.
Cue kicks off a background index for every warming track it saw, so calling again a moment later usually returns them warm. Read sync_status per track: error exists to keep an outage from reading as a settled fact about your track, so don’t treat the two as interchangeable when you decide whether to pick a different track. sync_points_per_track sets how many points you get per track when they are warm (1–12, default 4). For one track in depth, or to force the index to be built, use /v1/align. That endpoint does build a cold profile, as a job.

​
The response shape

The default response is lean: identifiers, score, tempo, whether it’s instrumental, and duration. ?expand=full swaps in the full public track object, with title, artist, tags, energy and musical key, and adds a candidate_pool array to the lane. Responses carry identity and analysis, not audio. See Render under your own license.

​
What it costs

**0.005percall∗∗,whetheritanswers‘200‘orcompletesasajob,andwhetherornotyouaskedfor‘includesync‘.Analysisisbilledseparately,once,whenyouingestthevideo,at0.005 per call**, whether it answers `200` or completes as a job, and whether or not you asked for `include_sync`. Analysis is billed separately, once, when you ingest the video, at 0.06 per minute of its length. However many times you match against that video afterwards, you pay only the flat match price. A call that errors bills nothing. See Metering & pricing. Over MCP the same thing is the match_music tool.