---
title: "Get the beats of the background music"
method: GET
path: "/v1/videos/{id}/background-music/beats"
tags: ["Videos"]
---

# Get the beats of the background music

`GET /v1/videos/{id}/background-music/beats`

## Request

- Base URL: `https://api.tella.com`
- URL: `https://api.tella.com/v1/videos/{id}/background-music/beats`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/withchima/apis/tella-public-api/docs/v1/videos/:id/background-music/beats/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns the tempo, every beat and every bar's first beat (downbeat) of the video's background music, in ms on the video's playback timeline: the track starts at 0 and restarts every `trackDurationMs` until the video ends, so the beats repeat with it. Use them to cut, start overlays or animate on the beat. Each track is analyzed once and cached; the first request for a new track can take a few seconds, and answers 503 `unavailable` if the analysis is still running, so retry.

## Path parameters

- `id` string, required: Unique video identifier

## Response `200`

OK

- MusicBeatsResponse: Tempo, beats and bars of a music track, analyzed once per track and cached
  - `beatsMs` number[], required: Every beat, in ms: on the video's playback timeline for background music (the same times as `get_timeline`), in source time for a source
  - `beatsPerBar` integer, required: Beats in each bar: 4, or 3 for a waltz-like meter
  - `bpm` number, required: Tempo in beats per minute. 0 when the track has no beat at all
  - `confidence` number, required: How clearly the track has a pulse, 0 to 1. Steady produced music is usually above 0.4; beatless ambient music below 0.1, where the beats are only a guess
  - `downbeatsMs` number[], required: The first beat of every bar, a subset of `beatsMs`. Cut or start a motion on these for the strongest musical accents
  - `durationMs` number, required: Length of the timeline the beats are on: the video's playback duration for background music, the source's duration for a source
  - `trackDurationMs` number, required: Length of one pass of the track. Background music restarts after it, so its beat grid restarts too

## Other responses

- `400`: The request was malformed or contained invalid parameters.
- `401`: Authentication is required. Provide a valid API key.
- `403`: You don't have permission to access this resource.
- `404`: The requested resource was not found.
- `409`: The request conflicts with the resource's current state, e.g. an Idempotency-Key whose first request is still in progress. Retry once it settles.
- `429`: You have exceeded the rate limit. Please slow down.
- `500`: An unexpected error occurred
- `501`: The requested operation is not implemented.
- `503`: A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay.

## Changes

> 72 revisions in range; 1 not diffed.

- **2026-10-28** `12af2f620d6c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/withchima/apis/tella-public-api/changes/v1/videos/:id/background-music/beats/get.md)

---

[API](https://skmtc.dev/withchima/apis/tella-public-api.md) - [All operations](https://skmtc.dev/withchima/apis/tella-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/withchima/apis/tella-public-api/revisions/ca74daaf9201?raw)