Limits and capacity

The numbers an integration has to design around, in one place.

Video

	Supported
Containers	MP4, MOV, WebM. Declare a video/* content_type (or application/octet-stream).
Codecs	Anything a standard ffmpeg build decodes — H.264, H.265/HEVC, VP8, VP9. Every upload is re-encoded for analysis, so no particular codec or bitrate is required.
Compression	No requirement. A phone camera’s default output is fine; heavy re-compression costs detail at the joints.
File size	Up to 500 MB. Larger is refused at create with 400 clip_too_large.
Duration	Up to 180 seconds — of the trim window, when you send one — or 120 s for movements analysed on our slower tier. Which movements those are differs per environment, so read the ceiling for a movement from GET /api/exercises/?activity=… (max_clip_duration_s, or max_clip_duration_s_by_exercise when you know the exercise). Longer is refused at create with 400 clip_too_long. 60 seconds or less is what we recommend: film the reps you want analysed. A session that renders with original_quality: true (the analysed video at the clip’s own resolution, up to 4K at 30 fps — see Uploading a video) is held to 30 seconds on top of that (the frame budget of that render, which runs twice with blur_face; the smaller ceiling wins): the same 400 clip_too_long, with max_duration_s: 30.
Resolution	Any, landscape or portrait. Analysis runs at a 1920-pixel long side (1920×1080 or 1080×1920); running uses up to 3840 on a 4K source. Smaller sources are scaled up, which adds no detail — shoot 1080p.
Frame rate	Any. Analysis runs at up to 30 fps, or up to 60 fps for running, agility, tennis, padel, badminton, bowling, ice_hockey, jump, baseball, weightlifting and fencing, and up to 120 fps for pickleball. A slower source is analysed at its native rate, never duplicated up. Shoot 60 fps for fast movements.

Both ceilings are checked when you call POST /api/sessions/ — and again on POST /api/sessions/{id}/reanalyze/ — against the object you uploaded, and before any quota is touched: a refused clip costs nothing. Creating before the PUT has finished is refused the same way, with 400 clip_not_found. The 400 body carries the live ceiling as max_duration_s / max_bytes, so read it from there rather than hard-coding it.

{
  "detail": "clip_too_long",
  "code": "clip_too_long",
  "video_url": "The video is 240 s long; the limit is 180 s. Trim it to the reps you want analysed — a trim window is enough — and try again.",
  "max_duration_s": 180
}

Rate limits

Two calls are limited per API key — not per IP address, and not per team:

Endpoint	Default ceiling
POST /api/sessions/upload-intent/	60 requests / minute
POST /api/sessions/	30 requests / minute

Over the limit you get 429 with {"detail": "rate_limited"} and a Retry-After header carrying the seconds to wait. A refused call reaches neither the database nor your quota. Honour Retry-After rather than hard-coding the ceilings above — they are set per environment.

A few other endpoints carry their own per-caller limits:

Endpoint	Default ceiling
POST /api/sessions/probe/	60 requests / minute
GET /api/sessions/probe/{id}/	120 requests / minute
POST /api/solutions/runs/{id}/refresh-ai/	30 requests / hour

Their 429 carries DRF’s standard prose detail rather than rate_limited, so branch on the status code and Retry-After, never on the text.

Everything else — including polling GET /api/sessions/{id}/ — is not rate-limited. Poll about every 2.5 seconds and back off (see The analysis lifecycle).

Many uploads at once

What happens when hundreds of your users submit a clip within minutes of each other — after an event, a campaign, or a quarterly-assessment reminder:

• Accepted and queued. Every session that passes create is stored and queued as pending; nothing accepted is dropped. Sessions are analysed concurrently, in the order they arrived.
• Throttled only at submission. The per-key ceiling above bounds how fast one key can submit, not how many sessions can be waiting. 1,000 sessions through one key submit in about 35 minutes; pace the loop to Retry-After.
• Rejected only for quota or billing. 402 quota_exhausted when the team’s allowance runs out, 402 subscription_suspended when payment has failed. Both are raised before anything is created. A session that fails during analysis gives its quota slot back automatically.
• Shared fairly. When several customers have work waiting, no single team can hold all of the analysis capacity; a team alone in the queue gets all of it.
• Scaled. GPU-backed analysis scales out automatically with demand — the first session after a quiet period can take about 10 seconds longer while capacity starts. Throughput for a large burst is minutes to a few hours depending on the movement mix; typical single clips finish in tens of seconds.

If you can tell us when a large assessment window opens, we can schedule capacity for it so results come back at single-clip speed. Higher or reserved capacity for scheduled assessment windows is available on Strategic contracts — talk to your account manager.

Related

• Uploading a video — the three-step flow.
• Errors — every code, including 429 and the clip ceilings.
• Quota and plans — what costs a session.
• Metric dictionary — every field a session returns.