---
title: "Identify (audio recognition)"
method: POST
path: "/v1/tracks/identify"
tags: ["Tracks"]
---

# Identify (audio recognition)

`POST /v1/tracks/identify`

## Request

- Base URL: `https://api.sonovault.now`
- URL: `https://api.sonovault.now/v1/tracks/identify`
- Auth: API key in header `x-api-key`

Recognise a track from audio. Send the raw audio file and you get back the best-matching catalog tracks, ranked, each with a confidence score. Costs 10 + ceil(MB) credits. A request that would cost more credits than you have left this month is refused with a 429 before any matching runs. Paid plans only.

**Requires a paid plan**: the free tier returns `403` for this endpoint.

**How much audio to send, cost & retries**

- **Send the whole track (or a generous section), not a short clip.** The part that matches our catalog reference can sit anywhere (often the main hook a few minutes in, not the intro), so a snippet from the wrong section misses the match even though the track is in the catalog. ~10 s is the minimum; more audio is more reliable.

- You're billed on the **bytes you upload** (10 + ceil(MB)), so a full ~4-min track is ~15–20 credits. On quality: **320 kbps gives the best result**, 128 kbps is the best value, and lossless is no better than 320 while costing more. To shrink the upload, **downsample to mono 16 kHz** (the measured safe floor, do not go lower), accepting that downsampling trades some accuracy for the saving. Trimming to a few seconds is cheaper but risks a miss.

- On a miss we **automatically scan deeper windows** of your audio and vote across them before returning no match, so there is nothing to retry by hand.

**Response**

- `matched` (boolean) and `results` - the matching catalog tracks, best match first. Each result is slim: `id`, `title`, `artists`, and `confidence` (a 0–1 score; higher means a more certain match).

- Need ISRC, genre, release info, or cross-platform links? Look the track up by `id` with `GET /v1/tracks/:id` (or `/v1/tracks/links`). Identify keeps its response small on purpose.

- `credits_charged` - credits billed for this call.

## Request body

- object

## Response `200`

Successful response

- object
  - `matched` boolean, required: `true` when at least one candidate cleared the confidence gate.
  - `results` IdentifyResult[], required: Candidate matches, best first. Empty array when nothing matched.
    - `id` integer, required: Sonovault track ID of the matched track.
    - `title` string, required: Track title.
    - `artists` TrackArtist[], required: Artist credits on the matched track.
      - `id` integer, required: Artist ID. Use it with `GET /v1/artists/:id`.
      - `name` string, required: Artist name as credited.
      - `is_primary` boolean, required: `true` for a main artist, `false` for a featured or supporting credit.
      - `is_remixer` boolean, required: `true` when the credit is for a remix of the track.
    - `confidence` number, required: Match confidence, 0 to 1. Higher is more certain.
  - `credits_charged` integer, required: Credits billed for this call: 10 + ceil(MB uploaded).

---

[API](https://skmtc.dev/sonovault/apis/sonovault-api.md) · [All operations](https://skmtc.dev/sonovault/apis/sonovault-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sonovault/apis/sonovault-api/revisions/0152fff23f2c?raw)