Longitudinal API

Most analyze endpoints score one recording on its own. The Longitudinal API adds a second question: how does this recording compare to the same person's previous ones?

You collect recordings into a group, and Amplifier maintains a personal baseline for that group. Each new submission can then be scored against that history — returning a baseline, the deviation from it, and a trend — alongside the usual per-recording result.

Two ways to read a group:

Concepts

Group. A caller-named container for jobs, scoped to your account. You choose the group_id — a stable identifier from your own system (a user id, a participant code) works well. Groups are created explicitly with POST /v2/groups, or implicitly the first time you submit audio to one.

Raw vs. longitudinal analyze. Every analyze endpoint has two group-aware forms:

• .../groups/{group_id}/analyze — registers the job into the group, but scores the recording on its own.
• .../groups/{group_id}/analyze/longitudinal — registers the job and scores it against the group's history.

Both contribute to the group's history once the job reaches done, and both cost the same — the two forms bill and rate-limit identically. The only difference is the response: the raw form returns the standard result, the longitudinal form adds the baseline and deviation fields. Use the raw form when a given call does not need them.

Recording time. Pass recorded_at when the audio was captured earlier than it was uploaded. Longitudinal ordering and time-decay use it; it falls back to the job's created_at when omitted.

History window. Group computations read a bounded window: completed jobs recorded within the last 270 days, capped at the 1,000 most recent. Everything the trajectory endpoint returns — data_points included — comes from that window (done_job_count excepted; it counts the whole group), and recency-weighting applies within it, so the oldest readings in the window influence the baseline least.

Credits and rate limits. Each analyze endpoint bills and rate-limits exactly like its own non-group counterpart: the model and use-case variants like POST /v2/models/{model_name}/analyze, the sign and condition variants like POST /v2/signs/{sign_name}/analyze. Group lifecycle, membership, and state endpoints consume no credits. See Billing & Cost.

POST /v2/groups

curl -X POST https://api.amplifierhealth.com/v2/groups \
-H "X-Account-ID: your-account-id" \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"group_id": "daily-checkins"}'

{
  "group_id": "daily-checkins",
  "job_count": 0,
  "created_at": "2026-05-29T10:00:00Z"
}

GET /v2/groups

curl -X GET "https://api.amplifierhealth.com/v2/groups" \
-H "X-Account-ID: your-account-id" \
-H "X-API-Key: your-api-key"

{
  "groups": [
    {
      "group_id": "daily-checkins",
      "job_count": 12,
      "done_job_count": 10,
      "earliest_recorded_at": "2026-05-01T08:30:00Z",
      "latest_recorded_at": "2026-05-29T08:30:00Z",
      "created_at": "2026-05-01T09:00:00Z",
      "updated_at": "2026-05-29T09:00:00Z"
    }
  ],
  "page": 0,
  "total_pages": 1
}

DELETE /v2/groups/{group_id}

curl -X DELETE https://api.amplifierhealth.com/v2/groups/daily-checkins \
-H "X-Account-ID: your-account-id" \
-H "X-API-Key: your-api-key"

{ "group_id": "daily-checkins", "deleted": true }

GET /v2/groups/{group_id}/jobs

curl -X GET "https://api.amplifierhealth.com/v2/groups/daily-checkins/jobs?status=done" \
-H "X-Account-ID: your-account-id" \
-H "X-API-Key: your-api-key"

{
  "group_id": "daily-checkins",
  "total_jobs": 10,
  "jobs": [
    {
      "job_id": "job_aaa",
      "status": "done",
      "recorded_at": "2026-05-01T08:30:00Z",
      "created_at": "2026-05-01T09:14:00Z",
      "use_case": null,
      "condition": null,
      "audio_duration_seconds": 27.4
    },
    { "...": "..." }
  ],
  "page": 0,
  "total_pages": 1
}

POST /v2/groups/{group_id}/jobs

curl -X POST https://api.amplifierhealth.com/v2/groups/daily-checkins/jobs \
-H "X-Account-ID: your-account-id" \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"job_ids": ["job_ddd", "job_eee", "job_fff", "job_ggg", "job_hhh"]}'

{
  "status": "accepted",
  "added": ["job_ddd", "job_eee", "job_hhh"],
  "skipped": { "job_fff": "already_in_group" },
  "not_found": ["job_ggg"],
  "not_yet_done": ["job_hhh"]
}

DELETE /v2/groups/{group_id}/jobs/{job_id}

curl -X DELETE https://api.amplifierhealth.com/v2/groups/daily-checkins/jobs/job_bbb \
-H "X-Account-ID: your-account-id" \
-H "X-API-Key: your-api-key"

{ "status": "accepted", "removed": "job_bbb" }

Analyze extensions

Four endpoints mirror the standard analyze endpoints, adding groups/{group_id} to the path. They register the job into the group at submission — creating the group if it is new — and score the recording on its own, without historical context.

Example

curl -X POST https://api.amplifierhealth.com/v2/models/apex/groups/daily-checkins/analyze \
-H "X-Account-ID: your-account-id" \
-H "X-API-Key: your-api-key" \
-F "audio=@recording.wav;type=audio/wav" \
-F "recorded_at=2026-05-01T08:30:00Z"

Example response

{
  "job_id": "job_aaa",
  "status": "queued",
  "group_id": "daily-checkins",
  "recorded_at": "2026-05-01T08:30:00Z",
  "created_at": "2026-05-01T09:14:00Z"
}

Longitudinal analyze

The same four endpoints with /longitudinal appended. These score the new recording against the group's history, adding baseline and deviation fields to each signal. The job is registered into the group as well, so it becomes part of the history for later calls.

Example

curl -X POST https://api.amplifierhealth.com/v2/models/apex/groups/subject-8f2a/analyze/longitudinal \
-H "X-Account-ID: your-account-id" \
-H "X-API-Key: your-api-key" \
-F "audio=@recording.wav;type=audio/wav" \
-F "recorded_at=2026-05-29T08:30:00Z"

Example completed job

Poll GET /v2/jobs/{job_id} until status is done. The job read returns the standard v2 job object — group_id and recorded_at are returned on the submission response above, so keep them alongside the job_id you stored:

{
  "job_id": "job_xxx",
  "status": "done",
  "created_at": "2026-05-29T09:00:00Z",
  "completed_at": "2026-05-29T09:00:45Z",
  "result": {
    "summary": { "...": "..." },
    "signals": [
      {
        "name": "stress",
        "score": 0.71,
        "level": "elevated",
        "flagged": true,
        "latest_score": 0.68,
        "baseline_score": 0.35,
        "deviation_from_baseline": 0.33,
        "anomaly": true,
        "z_score": 2.4,
        "population_z": 1.93
      }
    ],
    "audio_quality": { "...": "..." },
    "extended_metrics": { "...": "..." }
  }
}

GET /v2/groups/{group_id}/longitudinal

curl -X GET "https://api.amplifierhealth.com/v2/groups/daily-checkins/longitudinal?signal=stress" \
-H "X-Account-ID: your-account-id" \
-H "X-API-Key: your-api-key"

{
  "status": "done",
  "group_id": "daily-checkins",
  "computed_at": "2026-05-29T09:00:00Z",
  "min_data_points_met": true,
  "min_data_points_required": 3,
  "done_job_count": 10,
  "signals": [
    {
      "name": "stress",
      "data_points": [
        { "job_id": "job_aaa", "recorded_at": "2026-05-01T08:30:00Z", "score": 0.22, "level": "low",       "flagged": false, "anomaly": null  },
        { "job_id": "job_bbb", "recorded_at": "2026-05-15T08:30:00Z", "score": 0.61, "level": "moderate", "flagged": true,  "anomaly": false },
        { "job_id": "job_ccc", "recorded_at": "2026-05-29T08:30:00Z", "score": 0.81, "level": "elevated", "flagged": true,  "anomaly": false }
      ],
      "trajectory": { "direction": "up", "slope": 0.0211, "data_points_used": 3, "resolvable": true },
      "baseline_score": 0.28,
      "latest_score": 0.81,
      "change_absolute": 0.59,
      "flagged_rate": 0.67,
      "z_score": 1.9,
      "population_z": 2.37,
      "status": "ok",
      "min_data_points_met": true,
      "baseline_personal_weight": 0.37
    }
  ]
}

{ "status": "running", "group_id": "daily-checkins" }

GET /v2/groups/{group_id}/aggregate

curl -X GET "https://api.amplifierhealth.com/v2/groups/study-cohort-a/aggregate" \
-H "X-Account-ID: your-account-id" \
-H "X-API-Key: your-api-key"

{
  "status": "done",
  "group_id": "study-cohort-a",
  "computed_at": "2026-05-28T10:05:00Z",
  "job_count": 150,
  "signals": [
    {
      "name": "stress",
      "distribution": {
        "none": 0.32,
        "low": 0.22,
        "consider": 0.21,
        "moderate": 0.18,
        "elevated": 0.07
      },
      "mean_score": 0.41,
      "std_score": 0.18,
      "flagged_rate": 0.46,
      "job_count": 150
    }
  ]
}

Errors

The analyze endpoints on this page return the same codes as POST /v2/models/{model_name}/analyze — including AUDIO_TOO_SHORT, AUDIO_TOO_LONG, UNSUPPORTED_FORMAT, and AUDIO_POOR_QUALITY.

Group-specific conditions:

For the full list and retry guidance, see Error Reference.