MatchTune Audit API

Quickstart

Processing is asynchronous: you submit posts, then come back for the results. A post usually takes a few minutes. It can take up to about 30 minutes when the target-library lookups are busy.

curl -X POST https://audit-api.matchtune.com/v1/requests \
  -H "X-API-Key: ak_your_key" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"url": "https://www.youtube.com/watch?v=XXXXXXXXXXX"},
                {"url": "https://www.tiktok.com/@example_brand/video/1234567890123456789"}]}'

  -d '{"project_code": "ABC-2607161", "external_request_id": "batch-2026-09-22-001",
      "items": [{"url": "https://www.instagram.com/p/XXXXXXXXXXX/",
                 "tracked_account": "example_brand", "external_id": "post-48213",
                 "metadata": {"campaign": "spring-2026", "market": "FR"}}]}'

201 Created{ "request_id": "3f2b8c1e-5a7d-4e9b-8c21-6d0f4a9b7e10", "external_request_id": "batch-2026-09-22-001",
  "total_items": 1, "trace_id": "5e1c9a7b3d2f48e6a0b4c8d7e2f1a9b3", "reused": false,
  "items": [ { "job_id": "b41d7e92-8c0a-4f63-9e15-2a7c6f3d8b04", "position": 0, "url": "https://www.instagram.com/p/XXXXXXXXXXX/", "external_id": "post-48213" } ] }

curl https://audit-api.matchtune.com/v1/requests/3f2b8c1e-5a7d-4e9b-8c21-6d0f4a9b7e10 \
  -H "X-API-Key: ak_your_key"

curl https://audit-api.matchtune.com/v1/requests/3f2b8c1e-5a7d-4e9b-8c21-6d0f4a9b7e10/results \
  -H "X-API-Key: ak_your_key"

Authentication

Every call needs your API key. Send it in the X-API-Key header, or as Authorization: Bearer ak_… (both are declared as security schemes in the OpenAPI document). Keys start with ak_ and are issued by MatchTune. We store only a hash of your key, so we can't show it to you again. If you lose it, ask us to rotate it: the old key stops working immediately.

Each key belongs to one customer account, and everything is scoped to that account:

• Requests you create are filed under your account. Any customer_id you put in the body is ignored.
• Lists only contain your requests.
• Requests and items of other accounts answer 404 Not Found, exactly as if they didn't exist.

A missing, unknown or disabled key gets 401 Unauthorized with error code UNAUTHORIZED.

Requests, items and steps

A request is one submission: a batch of up to 100,000 URLs. Each URL becomes an item with its own job_id. Items are processed independently and in parallel, so one broken link never holds up the others.

A request can end up with more items than you submitted: a carousel that holds several videos is audited one item per video. Read total_items from the request rather than counting what you sent.

Each item moves through four steps, in this order. An item's current_stage is always one of them.

1. DOWNLOAD
2. PROCESSING
3. ENRICHMENT
4. COMPLETE

Carousels

An Instagram carousel can hold several videos, each with its own music. We audit every video slide as its own item: the item you submitted keeps the slide its url points at (or the first video when the url names the carousel itself), and each further video slide is added to the request as a new item while the request runs. Image slides produce nothing.

• A slide item has parent_job_id (the item it was split from) and inherits its external_id, metadata and tracked_account. It appears in /items, /results and webhooks like any other item, and the request's total_items grows accordingly.
• In its result, POST URL is the slide's own link (https://www.instagram.com/p/<slide id>/), PARENT POST URL is the carousel, and POST TYPE is Carousel. Date, caption, likes and comments are the carousel's.
• A carousel with no video at all is one item with AUDIO STATUS No Audio.
• Slides are added during the DOWNLOAD step, so poll the request (or list its items) rather than assuming the list is final at submission time.

Submitting one carousel that holds two videos gives two records:

GET /v1/requests/{id}/results{
  "results": [
    { "job_id": "5d1b0fb3-…", "parent_job_id": null, "position": 0,
      "result": { "POST TYPE": "Carousel",
                  "POST URL": "https://www.instagram.com/p/SLIDE1/",
                  "PARENT POST URL": "https://www.instagram.com/p/CAROUSEL/", … } },
    { "job_id": "e6edb49c-…", "parent_job_id": "5d1b0fb3-…", "position": 2,
      "result": { "POST TYPE": "Carousel",
                  "POST URL": "https://www.instagram.com/p/SLIDE2/",
                  "PARENT POST URL": "https://www.instagram.com/p/CAROUSEL/", … } }
  ]
}

Statuses

Items, requests and the individual steps of an item share one set of statuses. An item's current_stage tells you which step it is in.

A request's status becomes COMPLETED once every item has finished, whether the item completed or failed. Always check each item's status, not only the request's.

The result document

Each completed item has one result document. The keys are in upper case so they map directly onto audit spreadsheet columns, and an empty value is written -, as in the spreadsheet. The document contains those columns and nothing else; the item's job_id is on the item and results endpoints around it.

Audio category

AUDIO CATEGORY takes one of these values:

Only the first three contain music we identify. For Dialogue Only, Sound Effects Only, Silent Track and Mixed Sources (several short, overlapping sound sources, where a match is far more often wrong than right) no track is reported and AUDIO STATUS is Audio Not Recognized.

Re-uploads and covers

Social platforms are full of copies of commercial songs published under an uploader's own name, sometimes with the real performer hidden in the title ("Song (feat. Real Artist)" by an anonymous account). Recognition services index those copies as tracks in their own right. When we can establish beyond doubt which recording a copy reproduces, the track columns carry the original — its title, artist, label and ISRC — so the licensing question is answered against the real rightsholder. A genuine collaboration or a remix is never rewritten.

Match confidence

Every recognised track comes with MATCH CONFIDENCE. We report a track as High only when it is established: two independent recognition services name the same recording, one service matches strongly and nothing contradicts it, or a fingerprint check against the catalogue's own recording confirms it. When several candidates compete, or the only one is too weak to stand on its own (for example a single service matching a copy with no ISRC), nothing is established: the post is reported as Audio Not Recognized, with no track. A wrong identification costs more than a miss.

Fields

Example

A YouTube post, recognised{
  "PLATFORM": "YouTube",
  "POST URL": "https://www.youtube.com/watch?v=XXXXXXXXXXX",
  "POST ORIGIN": "example_brand",
  "TRACKED ACCOUNT": "example_brand",
  "ACCOUNT TYPE": "Owned",
  "POST DATE": "2024-05-01 09:12:44",
  "AUDIO STATUS": "Audio Recognized",
  "AUDIO CATEGORY": "Music Only",
  "IN TARGET LIBRARY": "No",
  "MUSIC SOURCE": "Not Found in Target Libraries",
  "REVIEW FLAG": "-",
  "MATCH CONFIDENCE": "High",
  "RISK STATUS": "At Risk",
  "TRACK NAME": "Example Track",
  "TRACK ARTIST": "Example Artist",
  "TRACK RECORD LABEL": "Example Records",
  "TRACK ISRC": "ZZX012600001",
  "VIDEO DURATION (SEC)": 13,
  "MUSIC DURATION (SEC)": 13.009,
  "MUSIC PRESENCE SCORE": 94.8,
  "POST LIKES": 312,
  "POST COMMENTS": 7,
  … plus the remaining fields listed above
}

Callbacks

When a request includes callback_url, we POST a JSON event to that URL for each of these moments:

POST {your callback_url}{
  "event": "item.completed",
  "request_id": "3f2b8c1e-5a7d-4e9b-8c21-6d0f4a9b7e10",
  "external_request_id": "batch-2026-09-22-001",
  "job_id": "b41d7e92-8c0a-4f63-9e15-2a7c6f3d8b04",
  "external_id": "post-48213",
  "metadata": { "campaign": "spring-2026", "market": "FR" },
  "parent_job_id": null,
  "status": "COMPLETED",
  "result": { … the result document … },
  "error": null,
  "timestamp": "2026-09-22T14:06:24.976633+00:00"
}

Every delivery carries three headers: X-MatchTune-Event (the event name), X-MatchTune-Delivery (an id that stays the same across retries of one event, so you can drop duplicates) and X-MatchTune-Signature.

Verifying the signature

Your account has a webhook secret (MatchTune gives it to you with your key). The signature header is t=<unix seconds>,v1=<hex> where v1 is HMAC-SHA256(secret, "<t>.<raw request body>"). Compute it over the body bytes exactly as received, compare in constant time, and reject timestamps older than five minutes:

# Python
import hmac, hashlib, time
def verify(secret, body: bytes, header: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300: return False
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Delivery and retries

• Answer with any 2xx within 10 seconds; do the work afterwards.
• Anything else, or a timeout, is retried after 1 s, 5 s and 25 s, then given up. Use /results to catch up on anything you missed: it is always the source of truth.
• Deliveries are sent from 51.91.64.130; allowlist that address if your endpoint filters by source.
• Deliveries can arrive out of order, and rarely twice. Key on job_id, not on arrival order and not on external_id alone: a carousel's slides share the external_id of the item they came from.

Errors and limits

Every error, whatever its status, has the same shape: a machine-readable code, a message for humans, a trace_id to quote to support (also sent in the X-Trace-Id response header) and, when useful, details:

429 Too Many Requests{
  "error": {
    "code": "RATE_LIMITED",
    "message": "daily limit of 500 items reached (480 used in the last 24 h, 30 requested)",
    "trace_id": "5e1c9a7b3d2f48e6a0b4c8d7e2f1a9b3",
    "details": { "limit": 500, "used_24h": 480, "requested": 30 }
  }
}

Item errors

When an item fails, its last_error has a class, the stage where it stopped, a readable message and, for downloads, the platform's own reason.

Pagination

List endpoints use a cursor. Pass the next_cursor you received as cursor on the next call, until next_cursor is null. For /items and /results it is the item position; for /requests it is an opaque string. Never build a cursor yourself.

Safe retries

Send an Idempotency-Key header with POST /v1/requests (any unique string, such as your own batch id). If the call is repeated with the same key, you get back the original request with "reused": true instead of a duplicate.

OpenAPI document

The machine-readable contract is at /openapi.json (OpenAPI 3.1): both security schemes, every request and response schema including the result document and the webhook event, and the error envelope on each operation. Point your generator or API client at it.