---
title: "Get the beats of an audio or video source"
method: GET
path: "/v1/sources/{sourceId}/beats"
tags: ["Sources"]
---

# Get the beats of an audio or video source

`GET /v1/sources/{sourceId}/beats`

## Request

- Base URL: `https://api.tella.com`
- URL: `https://api.tella.com/v1/sources/{sourceId}/beats`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/withchima/apis/tella-public-api/docs/v1/sources/:sourceId/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 an audio or video source owned by the caller or their workspace, in ms of source time. Each source is analyzed once and cached; the first request can take a few seconds, and answers 503 `unavailable` if the analysis is still running, so retry.

## Path parameters

- `sourceId` string, required: Streaming upload source 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

> 65 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/sources/:sourceId/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/0cc3fcd307ad?raw)