Skip to content
AiKYNETIX

Re-run the analysis pipeline for a session

POST
/api/sessions/{id}/reanalyze/
curl --request POST \
  --url http://localhost:8000/api/sessions/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/reanalyze/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "activity": "running", "exercise": "example", "handedness": "right", "camera_view": "side", "scuba_session_meta": { "side_involved": "L", "condition": "control_no_arms", "arms_engaged": true, "fin_model": "", "fin_stiffness": "", "borg_residual_post_bout": 1, "borg_sound_post_bout": 1, "calibration_scale_bar_m": 1 }, "client_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "barbell_mass_kg": 1, "walk_test_distance_m": 1 }'

Re-queues the pose pipeline against the existing video. Useful when the analyzers have been updated since the original run (new metric, fixed bug, model bump). Sets status back to pending and clears the previous analyzed_url so clients fall back to the raw upload until the worker repopulates it. Atomic — a session that’s already queued (pending) or running (processing) returns 409 reanalyze_in_flight rather than spawning a second worker that would race on metric writes. Returns 202 with the reset Session; poll as you would after POST /api/sessions/.

Re-route (optional, #775): pass activity + exercise (both, together) to re-derive the session under a DIFFERENT analyzer — for a misclassified capture or a clip that should now run as a newly-shipped exercise. The pair is validated against the taxonomy (400 on an invalid pair); stale metrics from the old exercise are cleared (coach notes preserved). Omit both to re-run under the current activity.

Reassign the client (optional, #923): pass client_id to move the session to another of the team’s clients before the re-run — the pipeline then recomputes the body-aware metrics + green zones against the new client’s profile (height / weight / gender / leg length). null unassigns. An unknown id or another team’s client is 400 client_not_found. Valid with or without the re-route pair — a client-only body re-runs under the current pair.

Quota. A session still holding its original create debit re-runs for free — that is the common case, and the ledger doesn’t move. A session that FAILED released its slot at failure time (so the failed attempt cost nothing), and the re-run re-takes it. That only fails when the slot was spent elsewhere in the meantime: 402 quota_exhausted, same payload as POST /api/sessions/. Retrying a clip our own pipeline just broke therefore never hits the paywall — the slot being re-taken is the one that failure returned.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string format: uuid

Request Body

Section titled “Request Body”

Optional body for POST /api/sessions/{id}/reanalyze/ (#775).

Omit everything to re-run under the session’s CURRENT activity (the default reanalyze). Pass activity + exercise (both) to re-derive the session under a DIFFERENT analyzer — a misclassified capture, or a clip that should now run as a newly-shipped exercise. Either way you may also pass the analysis metadata the chosen activity needs — handedness (dominant hand / foot), camera_view, or the scuba_session_meta sidecar — to correct it or supply it for the new analyzer; each is written onto Session.meta exactly as at upload, and only the keys you send are touched (the rest of meta is preserved). The pair is validated against the taxonomy server-side; the session resets to PENDING + re-runs with no new quota debit.

client_id (#923) reassigns the session to another of the team’s clients (or null to unassign) before the re-run, so the pipeline recomputes the body-aware metrics + green zones against the correct anthropometrics. It is valid on its own — no activity+exercise pair required — because a reassignment always re-runs under the current pair.

object
activity

Re-route the session to this activity. Requires exercise.

  • running - Running
  • walking - Walking
  • jump - Vertical Jump
  • weightlifting - Weightlifting
  • mobility - Mobility Assessment
  • workspace_wellness - Workspace Wellness
  • agility - Agility
  • fencing - Fencing
  • cycling - Cycling
  • tennis - Tennis
  • padel - Padel Tennis
  • bowling - Bowling
  • baseball - Baseball
  • football - Football
  • badminton - Badminton
  • cricket - Cricket
  • basketball - Basketball
  • scuba_diving - Scuba Diving
  • ice_hockey - Ice Hockey
  • american_football - American Football
  • fri - Falls Risk Indicator
string
Allowed values: running walking jump weightlifting mobility workspace_wellness agility fencing cycling tennis padel bowling baseball football badminton cricket basketball scuba_diving ice_hockey american_football fri
exercise

Exercise within the new activity — must be a valid preset for it (see GET /api/exercises/). Requires activity.

string
>= 1 characters <= 80 characters
handedness

Dominant hand / foot for handedness-aware activities (tennis, padel, badminton, baseball, basketball, cricket, fencing, football). Written to Session.meta.handedness; ignored by activities whose analyzers don’t read it.

  • right - Right-handed
  • left - Left-handed
string
Allowed values: right left
camera_view

Camera plane. front / back swap to the frontal analyzer for the activities that have one. Must be one of the new pair’s supported views — an unsupported plane is a 400 (#1829); see views_by_exercise in GET /api/exercises/?activity=…. Written to Session.meta.camera_view.

  • side - Side
  • front - Front
  • back - Back
string
Allowed values: side front back
scuba_session_meta

Scuba sidecar — required when re-routing to scuba_diving, ignored otherwise. Written to Session.meta.scuba.

object
side_involved
required
One of:
  • L - Left
  • R - Right
string
Allowed values: L R
condition
required

§5.2 condition tag. Used for cohort tagging on the dashboard + the report PDF cover. Must match the trial design — not derived from other fields, because the same diver shoots multiple conditions per session.

  • control_no_arms - Control — no arms
  • control_with_arms - Control — with arms
  • transtibial - Transtibial
  • transfemoral - Transfemoral
string
Allowed values: control_no_arms control_with_arms transtibial transfemoral
arms_engaged
required

Confound flag (§4.6). True when the diver was sculling / using arms for propulsion during the bout. Surfaces in the report so coaches know to filter symmetry numbers.

boolean
fin_model

Fin model — free-form (manufacturer + model).

string
"" <= 128 characters
fin_stiffness

Fin stiffness. Free-form: either a qualitative grade (soft / medium / stiff) or a numeric string with units (12 N·m/rad). Analyzer doesn’t consume it in V1; captured for the report + future fin-deflection v2 work.

string
"" <= 64 characters
borg_residual_post_bout

Borg CR-10 perceived exertion (residual side), 0–10.

integer
nullable <= 10
borg_sound_post_bout

Borg CR-10 perceived exertion (sound side), 0–10.

integer
nullable <= 10
calibration_scale_bar_m

Length of the in-frame calibration scale bar (§6.1), in metres. Optional — without it, body-aware distance metrics use body_scale_px(ctx) per the standard fallback.

number format: double
nullable
client_id

Reassign the session to this client before the re-run (#923) — body-aware metrics + green zones recompute against the new client’s profile. null unassigns. Must be one of the caller’s team’s clients (400 client_not_found otherwise). Unlike the analysis metadata, valid WITHOUT an activity + exercise pair: a client-only body reassigns and re-runs under the session’s current pair.

string format: uuid
nullable
barbell_mass_kg

(Re-)declare the barbell’s total load in kg for a weightlifting re-run (#1325). Key-presence semantics like client_id: a value writes Session.meta.barbell_mass_kg (an override re-run would otherwise clear it — stale meta doesn’t survive a repoint); null explicitly clears it; absent leaves the stored value alone on a plain re-run. Valid WITHOUT an activity + exercise pair — it doesn’t change WHICH analyzer runs, only an input it reads, so a mass-only body re-runs the current pair with the corrected load (e.g. a session uploaded before the load could be declared). Silently ignored when the target activity isn’t weightlifting.

number format: double
nullable >= 1 <= 500
walk_test_distance_m

(Re-)declare the measured course length in metres for a walking / Timed Walk re-run (#1493). Same key-presence semantics as barbell_mass_kg: a value writes Session.meta.walk_test_distance_m, null clears it, absent leaves the stored course alone. This is the correction path for a course entered wrong at upload — the walk itself is fine, only the number the speed is divided by was, and re-filming to fix a typo would be absurd. Valid WITHOUT an activity + exercise pair: it does not change WHICH analyzer runs, only an input it reads. Silently ignored when the target pair isn’t walking / Timed Walk.

number format: double
nullable >= 2 <= 100

Responses

Section titled “Responses”

202

Section titled “202”
Media typeapplication/json
object
id
required

Server-assigned UUID. Use the same value as session_id from the upload-intent step to keep the storage object key consistent.

string format: uuid
activity
required

Activity family — running, walking, jumps, weightlifting, agility, mobility, fencing, ergonomics. Drives which analyzer runs.

  • running - Running
  • walking - Walking
  • jump - Vertical Jump
  • weightlifting - Weightlifting
  • mobility - Mobility Assessment
  • workspace_wellness - Workspace Wellness
  • agility - Agility
  • fencing - Fencing
  • cycling - Cycling
  • tennis - Tennis
  • padel - Padel Tennis
  • bowling - Bowling
  • baseball - Baseball
  • football - Football
  • badminton - Badminton
  • cricket - Cricket
  • basketball - Basketball
  • scuba_diving - Scuba Diving
  • ice_hockey - Ice Hockey
  • american_football - American Football
  • fri - Falls Risk Indicator
string
Allowed values: running walking jump weightlifting mobility workspace_wellness agility fencing cycling tennis padel bowling baseball football badminton cricket basketball scuba_diving ice_hockey american_football fri
exercise

Specific movement within the activity (e.g. Treadmill, Back Squat, Single-Leg Stand). Pick from GET /api/exercises/?activity=....

string
<= 80 characters
name
required
string
seq_no
required

Stable per-team session number (#941), assigned at create time and immutable — the shared reference coaches use to point at a video (‘look at session 42’). Monotonic per team in creation order; survives filter / sort / pagination and reads the same for every teammate. Gaps appear where sessions were deleted (numbers are never reused). null on demo sessions (cross-team, deliberately unnumbered) and on the public /api/shared/{token}/ payload, where the team-internal ordinal is withheld from anonymous viewers.

integer
nullable
status
required

Lifecycle state: pending (queued) → processing (analyzer running) → completed (metrics + annotated mp4 ready) | failed (see failure_reason).

  • pending - Pending
  • processing - Processing
  • completed - Completed
  • failed - Failed
string
Allowed values: pending processing completed failed
video_url
Any of:
string format: uri
<= 1000 characters
analyzed_url
required

Public URL of the annotated playback mp4 — pose skeleton drawn over the original frames. Populated when status == 'completed'; empty before that and during reanalyze.

string format: uri
anonymized_url
required

Public URL of a face-anonymised copy of the source video WITHOUT the pose overlay (#1233) — the privacy-safe ‘raw’ source for the player’s overlay toggle. Populated only on Face-Blur sessions (blur_face == true); empty otherwise, when the best-effort clean render failed, and during reanalyze. On non-blur sessions the player toggles to video_url directly. On the public /api/shared/{token}/ payload the un-anonymised video_url is withheld for blur sessions and this field is the only ‘raw’ source.

string format: uri
pose3d_url
required

Public URL of the 3D pose sidecar JSON (#1356) — the per-frame 3D joint track uploaded next to the annotated mp4, consumed by the player’s interactive 3D viewer. Empty when the 3D lifter isn’t configured on the inference service, when its best-effort generation failed, and during reanalyze — clients then hide the 3D view. Served on the public /api/shared/{token}/ payload, EXCEPT on a Face-Blur session: it carries no imagery, but it reconstructs the athlete’s movement in full, so it is blanked there alongside video_url.

string format: uri
thumbnail_url
required

Public URL of a static JPG poster (~5-15 KB) extracted at ~0.5 s of the annotated mp4. The SPA renders this on the journal row instead of mounting a <video preload=metadata> per row, which avoids the main-thread freeze on long session lists. Empty when aikmodels couldn’t generate one — clients fall back to analyzed_url and decode the first frame themselves.

string format: uri
fps

Frame rate the session was ANALYSED at — read off the normalized file, not the upload. Every metric and per-frame derivative in the report is a function of this number, which is why it is the one reported. It is min(AIKMODELS_NORMALIZE_FPS, source_fps) (#1951), so on a 60 or 120 fps upload it reads BELOW what the coach filmed; compare source_fps to tell the two apart.

integer
nullable <= 32767
source_fps

Frame rate the camera actually captured at, probed before our normalize resample. Null on older sessions and when the probe could not run. Present so a client can say “filmed at 60, analysed at 30” rather than showing our rate as though it were the coach’s (#1951). May be fractional — 23.976 and 29.97 are real capture rates.

number format: double
nullable
duration_ms

Source video duration in milliseconds.

integer
nullable <= 2147483647
processed_at
required

ISO-8601 UTC timestamp of the session’s LAST successful analysis. Null until the first one completes; it is NOT cleared afterwards, so a session that delivered a report once and was then re-analyzed keeps its timestamp while sitting on pending/processing/failed.

string format: date-time
nullable
created_at
required

ISO-8601 UTC timestamp of session creation.

string format: date-time
client
required

UUID of the Client (athlete) the session is about. Optional but strongly recommended — without a client, body-aware metric adjustments fall back to defaults.

string format: uuid
nullable
uploaded_by
required

UUID of the Admin who uploaded the session. Team-scoped listings carry it so per-coach surfaces (e.g. the upload wizard’s recent-combos row) can filter to the current admin’s own history without leaking a teammate’s picks. null for legacy rows created before attribution was recorded.

string format: uuid
nullable
failure_reason
required

Human-readable explanation when status == 'failed'. Empty otherwise.

string
metrics
required

List of all SessionMetric rows attached to this session — joint angles, timings, scores, the full per-key catalogue the analyzer emitted. Empty until status == 'completed'.

Array<object>
object
key
string
value_num
number
nullable
value_json
object
metric_targets
required

Body-aware-adjusted green-zone bounds keyed by metric: {key: {min_good, max_good, amber_low, amber_high, higher_is_better, beta}}. Already accounts for the athlete’s gender + height — front-end can render the zone directly without re-applying any adjustment. amber_low / amber_high are the ONROM (amber) outer bounds of the three-tier clinical band (#521); both null ⇒ classic binary green zone (the front-end derives the wnl/onrom/high_risk tier from them). beta flags a metric that has not cleared clinical validation (UI shows a precision caveat). Empty list when the activity has no zone-defining specs.

object
key
additional properties
camera_view
required

side / front / back. Read-only; derived from the value passed at session create time. Lets the player UI badge the view and hide metric cards that don’t apply.

string
capture_findings
required

Capture-quality findings for a COMPLETED session (#1868) — the typed defect taxonomy evaluated from the inference service’s capture signals: [{code, severity, data}], e.g. {"code": "pose_sparse", "severity": "advisory", "data": {"detection_ratio": 0.42}}. Empty list = evaluated clean; null = the session predates capture evaluation (never conflate the two). Codes: pose_sparse / implausible_geometry / subject_too_far / camera_off_plane / subject_left_frame. Severity is advisory-only today — fatal capture problems FAIL the session and speak through failure_reason.

Array<object>
nullable
object
key
additional properties
handedness
required

right / left dominant hand or foot, or null. Read-only; from the value passed at create time. Seeds the reprocess dialog so a handedness-aware re-run keeps the athlete’s side instead of silently defaulting to right-handed (#775).

string
nullable
is_demo
required
boolean
progress
required

Worker’s most recent stage emit while this session is in flight. null for terminal states, queued sessions, and any read failure — the SPA renders a queued placeholder in those cases. Polled via the existing session-detail refetch (every 2 s while pending/processing); no separate endpoint.

object
stage
required

Pipeline stage the worker is currently executing (e.g. download, pose_extract, draw). The full stage list is hardcoded on each side and kept in sync via a contract test (apps/api side) — adding or renaming a stage is a cross-track PR per ADR-0011.

string
stage_idx
required

0-based index of stage in the worker’s stage order.

integer
frame_done
required

Frames processed so far inside the current stage. Only moves during stages with sub-progress (today: pose_extract); 0 elsewhere.

integer
frame_total
required

Total frame count for the current stage; 0 when the stage has no frame counter or the worker hasn’t computed it yet.

integer
has_active_share
required

Whether a live public share link exists for this session — so the player can offer Revoke on a session shared in an earlier visit. null means NOT REPORTED, which is every list response: the value is annotated by the session-detail view only, because a per-row lookup would be one query per session on a list that has no use for it. Treat null as ‘unknown’, not as ‘no share’.

boolean
nullable
locale
required

Language (en / ru / es) frozen on the share when the coach created/refreshed it — only populated on the public GET /api/shared/{token}/ response, where the /r/<token> page reads it to render its whole UI in the same language as the AI coaching paragraph (issue #339). null on the authenticated session endpoints, which follow the coach’s own UI locale.

string
nullable
blur_face
required

True when this session was created with the Blur Face option — the analysed video has the subject’s face anonymised. Read-only; false for every session created without the flag.

boolean
barbell_mass_kg
required

The lifter’s declared total bar load in kg, or null when never declared. Read-only; from the value passed at create time (#1325). Seeds the reprocess dialog so a weightlifting re-run keeps the declared load instead of silently losing it (the repoint clears stale meta by default).

number format: double
nullable
walk_test_distance_m
required

The declared walk-test course in metres, or null when the session has none (#1493). Read-only. Seeds the reprocess dialog so a Timed Walk re-run keeps the measured course — and so a course typed wrong at upload can be corrected there instead of re-filming a perfectly good walk.

number format: double
nullable
has_scuba_meta
required

True when this session already has a scuba session-meta sidecar on Session.meta.scuba. A boolean only — the clinical payload (side / condition / arms-engaged) is never exposed. The reprocess dialog gates on it: a scuba re-run that already has a sidecar carries the stored one over (no blind overwrite); one without it (legacy / re-routing in from another activity) must supply it (#775).

boolean
report_count
required

How many active Solution reports bind this session — the reverse of the report→sessions link, shown as a ‘used in N reports’ badge on the journal row (#1192). Only populated on the session-list endpoint (the view seeds a per-page map to avoid N+1); null everywhere else, where the FE simply omits the badge.

integer
nullable
reports
required

The active Solution reports that bind this session, each with a ready name + slug — powers the ‘used in N reports’ links on the single-session player (#1192). Only populated on the session-detail endpoint (the view seeds the reverse-scan for the one session); an empty list elsewhere, where the FE shows no links.

Array<object>
object
id
required
string
name
required
string
solution_slug
required
string
movement_guide
required

Movement Norms Library entry for this session’s movement (reference table + explanation), localised to the session’s locale. Populated ONLY on the public shared payload (#1118) so the /r/ report renders the guide without a second authenticated call; null on the authenticated app (which calls GET /api/movement-guide/) and when the library has no entry.

object
activity
required
string
exercise
required
string
what_it_measures
required

Plain-English description of the movement and what its variables capture.

string
key_fact
required

One evidence-backed fact, with citation where available.

string
demographics
required

How the bands shift by sex/age.

string
skill
required

What improves from beginner to advanced.

string
metrics
required

Per-metric reference row for the Movement Guide table. min_good/max_good are the team-default reference band (same as the Threshold configurator) in the metric’s canonical unit; evidence_basis is validated | experimental | assumed; reference_only metrics are library variables we don’t yet compute for a session.

Array<object>
object
key
required
string
label
required
string
unit
required
string
higher_is_better
required
boolean
nullable
min_good
required
number format: double
nullable
max_good
required
number format: double
nullable
evidence_basis
required
string
source
required
string
note
required
string
per_athlete
required
boolean
reference_only
required
boolean
Example
{
  "activity": "running",
  "status": "pending"
}

400

Section titled “400”
Media typeapplication/json
object
detail
required

Human-readable message, or a stable machine code for the cases a client branches on. The standard envelope for 400 (validation — a field-keyed object may appear instead), 401 (missing / invalid credentials), 403 (authenticated but not permitted), and 404 (absent — cross-team records are collapsed to 404 so the API never leaks the existence of another team’s data).

string
Examples
Example400—ClientNotOnThisTeam

`client_id` unknown, or owned by another team (collapsed to one 400)

{
  "detail": "client_not_found"
}

401

Section titled “401”
Media typeapplication/json
object
detail
required

Human-readable message, or a stable machine code for the cases a client branches on. The standard envelope for 400 (validation — a field-keyed object may appear instead), 401 (missing / invalid credentials), 403 (authenticated but not permitted), and 404 (absent — cross-team records are collapsed to 404 so the API never leaks the existence of another team’s data).

string
Examplegenerated
{
  "detail": "example"
}

402

Section titled “402”
Media typeapplication/json
object
detail
required

One of five canonical strings. The front-end paywall switches copy + CTA on this value (exact string equality — do not localise). quota_exhausted / seat_limit_reached / client_limit_reached / feature_not_in_plan lead to an upgrade CTA; subscription_suspended leads to a Billing Portal CTA so the buyer can update their payment method.

  • quota_exhausted - Session quota for the period reached 0
  • subscription_suspended - Stripe dunning in flight (past_due / unpaid)
  • seat_limit_reached - Adding another team member would exceed plan.max_seats
  • client_limit_reached - Adding another Client would exceed plan.max_client_profiles
  • feature_not_in_plan - The tier does not include this whole feature surface
string
Allowed values: quota_exhausted subscription_suspended seat_limit_reached client_limit_reached feature_not_in_plan
reset_at
required

ISO-8601 UTC timestamp the team’s current period ends. Null when the team has no live subscription (legacy un-migrated row). On Free + paid this is the renewal moment; quota refreshes to exactly plan.session_quota (NOT additive — leftover sessions don’t roll over).

string format: date-time
nullable
current_plan
required

The active plan’s role string (free, starter, professional, organization, strategic). Same value as current_role — kept as two separate fields for forward-compatibility with a future named-plan split where current_plan could carry an SKU and current_role the tier label.

string
current_role
required

The active plan’s role string. See current_plan.

string
feature

Which feature surface is locked. Present ONLY on feature_not_in_plan, so one modal can name what’s gated without a detail string per feature (#773). The only value today is agents (aikynetix/agents/services.py::AGENTS_FEATURE).

string
Example
{
  "detail": "quota_exhausted"
}

404

Section titled “404”
Media typeapplication/json
object
detail
required

Human-readable message, or a stable machine code for the cases a client branches on. The standard envelope for 400 (validation — a field-keyed object may appear instead), 401 (missing / invalid credentials), 403 (authenticated but not permitted), and 404 (absent — cross-team records are collapsed to 404 so the API never leaks the existence of another team’s data).

string
Examples
Example404—NoSuchSessionOnThisTeam

Absent, or owned by another team (collapsed to 404)

{
  "detail": "session_not_found"
}

409

Section titled “409”
Media typeapplication/json
object
detail
required

409 — the request conflicts with current state. detail is a stable code (e.g. reanalyze_in_flight, already_on_plan, email_in_use). Some 409s carry extra context fields alongside detail; those are documented on the specific endpoint that emits them.

string
Examples
Example409—Re-analysisAlreadyInFlight

409 — Re-analysis already in flight

{
  "detail": "reanalyze_in_flight"
}