Skip to content
AiKYNETIX

Peer standings for a client

GET
/api/clients/{id}/peers/
curl --request GET \
  --url http://localhost:8000/api/clients/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/peers/ \
  --header 'Authorization: Bearer <token>'

Where the athlete stands among ‘others like them’ (#1745, ADR-0044), per activity: the composite-score standing plus per-metric standings for the aggregated top metrics. Each standing names the rung of the fallback ladder it stands on (platform anonymised distribution / norm published band / team same-cell teammates) and the cohort cell, so the UI never pretends precision. Aggregates only — no other athlete’s data is readable through this endpoint; a distribution cell below the k-anonymity floor is absent by construction. Team-scoped — 404 for a client owned by another team.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

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

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json

Shape of GET /api/clients/{id}/peers/ — a lookup table of peer standings for the client detail page. Aggregates only: distributions and published bands, never another athlete’s data (ADR-0044).

object
client_id
required
string format: uuid
activities
required
Array<object>
object
activity
required
  • 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
score
required

Composite-score standing (latest scored session), or null.

object
source
required
  • platform - platform
  • norm - norm
  • team - team
string
Allowed values: platform norm team
percentile
required

Share of peers beaten, 0-100, direction-aware. Null on the norm rung.

number format: double
nullable
n
required

Peer count behind the number. Null on the norm rung.

integer
nullable
n_teams
required

Distinct teams in the cell. Platform rung only.

integer
nullable
cell
required

The cohort cell the standing was resolved against. An empty string means the dimension was widened out (ADR-0044’s ladder), so the UI can say “vs all intermediate females” instead of pretending precision.

object
gender
required
string
age_band
required
string
skill_level
required
string
band_min
required

Norm rung only.

number format: double
nullable
band_max
required

Norm rung only.

number format: double
nullable
band_position
required
One of:
  • below - below
  • inside - inside
  • above - above
string
Allowed values: below inside above
band_source
required

The published source behind the band. Norm rung only.

string
nullable
metrics
required

Only metrics where a rung of the fallback ladder resolved.

Array<object>

One metric’s peer standing on the internal client page (#1745). value is the SI aggregate the standing was resolved against — the page matches it to its own tiles by key.

object
key
required
string
value
required
number format: double
standing
required

Where the athlete stands among “others like them”.

source names the rung of the fallback ladder that answered: platform (anonymised platform-wide cell — percentile + n + n_teams), norm (published norms band — a position, never a percentile) or team (same-cell teammates — percentile + n).

object
source
required
  • platform - platform
  • norm - norm
  • team - team
string
Allowed values: platform norm team
percentile
required

Share of peers beaten, 0-100, direction-aware. Null on the norm rung.

number format: double
nullable
n
required

Peer count behind the number. Null on the norm rung.

integer
nullable
n_teams
required

Distinct teams in the cell. Platform rung only.

integer
nullable
cell
required

The cohort cell the standing was resolved against. An empty string means the dimension was widened out (ADR-0044’s ladder), so the UI can say “vs all intermediate females” instead of pretending precision.

object
gender
required
string
age_band
required
string
skill_level
required
string
band_min
required

Norm rung only.

number format: double
nullable
band_max
required

Norm rung only.

number format: double
nullable
band_position
required
One of:
  • below - below
  • inside - inside
  • above - above
string
Allowed values: below inside above
band_source
required

The published source behind the band. Norm rung only.

string
nullable
Examples
ExamplePeerStandings

Peer standings

{
  "client_id": "f6d52e64-3aa3-4a26-bac2-0fc9d718448d",
  "activities": [
    {
      "activity": "running",
      "score": {
        "source": "platform",
        "percentile": 78,
        "n": 84,
        "n_teams": 7,
        "cell": {
          "gender": "female",
          "age_band": "under_18",
          "skill_level": "intermediate"
        },
        "band_min": null,
        "band_max": null,
        "band_position": null,
        "band_source": null
      },
      "metrics": [
        {
          "key": "cmj_height",
          "value": 31.4,
          "standing": {
            "source": "norm",
            "percentile": null,
            "n": null,
            "n_teams": null,
            "cell": {
              "gender": "female",
              "age_band": "under_18",
              "skill_level": "intermediate"
            },
            "band_min": 24,
            "band_max": 34,
            "band_position": "inside",
            "band_source": "NSCA youth jump norms"
          }
        }
      ]
    }
  ]
}

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"
}

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—NoSuchClientOnThisTeam

404 — No such client on this team

{
  "detail": "client_not_found"
}