Groups API

Create groups and manage job membership.

A group is a caller-named container for jobs, scoped to your account. Create, list, delete groups; add or remove jobs. Analysis is Longitudinal API. Concepts (recorded_at, history window): Longitudinal concepts.

Create a group

POST /v2/groups

Create a group explicitly, before any audio is submitted to it.

Creating a group up front is optional — the analyze endpoints create one implicitly when the group_id is new. Use this endpoint when you want to register the group as a discrete step.

Request Body

Requests use Content-Type: application/json.

Field	Type	Required	Description
`group_id`	string	Yes	Your identifier for the group. Must be unique within your account. Up to 512 characters. Must start with a letter or digit; remaining characters may also include `.` `_` `~` `:` `-`
`model_version`	string	No	Model version the group runs, in `X.Y.Z` form (for example `2.1.0`). Fixed when the group is created and never changes. Omit it to use the current default version at creation. An invalid or unavailable value returns `400`. See Model versions.

Response

Returns 201 Created.

Field	Type	Description
`group_id`	string	The group identifier you supplied.
`job_count`	integer	Jobs currently in the group. `0` for a new group.
`model_version`	string	The group’s model version.
`created_at`	string	ISO 8601 creation timestamp.

Example

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", "model_version": "2.1.0"}'

const response = await fetch("https://api.amplifierhealth.com/v2/groups", {
  method: "POST",
  headers: {
    "X-Account-ID": process.env.AMPLIFIER_ACCOUNT_ID,
    "X-API-Key": process.env.AMPLIFIER_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "group_id": "daily-checkins",
    "model_version": "2.1.0"
  }),
});

const data = await response.json();

# Requires httpx: pip install httpx
import os
import httpx

response = httpx.post(
  "https://api.amplifierhealth.com/v2/groups",
  headers={
      "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"],
      "X-API-Key": os.environ["AMPLIFIER_API_KEY"],
  },
  json={
    "group_id": "daily-checkins",
    "model_version": "2.1.0",
  },
)

data = response.json()

Example response

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

Errors

HTTP	Condition
409	A group with this `group_id` already exists for your account.
400	`group_id` is empty, too long, or contains unsupported characters.
400	`INVALID_MODEL_VERSION` or `UNKNOWN_MODEL_VERSION`: `model_version` is not a well-formed, available version.

List groups

GET /v2/groups

List the groups belonging to your account, with job counts and observed date range.

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	0-based page number. Default: 0.

Response

Field	Type	Description
`groups`	array	Group objects, described below.
`page`	integer	The page returned.
`total_pages`	integer	Total pages available.

Each object in groups:

Field	Type	Description
`group_id`	string	The group identifier.
`job_count`	integer	Jobs in the group, in any status.
`model_version`	string	The group’s model version. Groups created before November 10, 2026 read as `2.0.0`.
`done_job_count`	integer	Jobs that have completed and contribute to group computations.
`earliest_recorded_at`	string or null	Earliest recording time in the group.
`latest_recorded_at`	string or null	Most recent recording time in the group.
`created_at`	string	When the group was created.
`updated_at`	string	When the group last changed — membership edits and recomputes of its cached state both move it.

Example

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

const response = await fetch("https://api.amplifierhealth.com/v2/groups", {
  headers: {
    "X-Account-ID": process.env.AMPLIFIER_ACCOUNT_ID,
    "X-API-Key": process.env.AMPLIFIER_API_KEY,
  },
});

const data = await response.json();

# Requires httpx: pip install httpx
import os
import httpx

response = httpx.get(
  "https://api.amplifierhealth.com/v2/groups",
  headers={
      "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"],
      "X-API-Key": os.environ["AMPLIFIER_API_KEY"],
  },
)

data = response.json()

Example response

{
  "groups": [
    {
      "group_id": "daily-checkins",
      "job_count": 12,
      "model_version": "2.0.0",
      "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 a group

DELETE /v2/groups/{group_id}

Delete a group, its membership records, and its stored longitudinal and aggregate results.

The jobs themselves are kept — they remain available through GET /v2/jobs/{job_id}. Only the group and its computed state are removed.

Path Parameters

Parameter	Type	Description
`group_id`	string	The group to delete.

Response

Field	Type	Description
`group_id`	string	The group that was deleted.
`deleted`	boolean	`true` on success.

Example

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"

const response = await fetch("https://api.amplifierhealth.com/v2/groups/daily-checkins", {
  method: "DELETE",
  headers: {
    "X-Account-ID": process.env.AMPLIFIER_ACCOUNT_ID,
    "X-API-Key": process.env.AMPLIFIER_API_KEY,
  },
});

const data = await response.json();

# Requires httpx: pip install httpx
import os
import httpx

response = httpx.delete(
  "https://api.amplifierhealth.com/v2/groups/daily-checkins",
  headers={
      "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"],
      "X-API-Key": os.environ["AMPLIFIER_API_KEY"],
  },
)

data = response.json()

Example response

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

Errors

HTTP	Condition
404	No group with this `group_id` exists for your account.

List group jobs

GET /v2/groups/{group_id}/jobs

List the jobs in a group, ordered by recording time. Returns job metadata only.

Always synchronous. For the full result of any listed job, call GET /v2/jobs/{job_id}.

Path Parameters

Parameter	Type	Description
`group_id`	string	The group to list.

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	0-based page number. Default: 0.
`from`	string	No	ISO 8601 date. Include jobs recorded at or after this time.
`to`	string	No	ISO 8601 date. Include jobs recorded at or before this time.
`status`	string	No	Filter by the membership status recorded for the job: `queued`, `running`, `done`, `failed`, or `timed-out`. Jobs registered at submission are recorded as `queued` and move to `done` on completion, so filter on `done` to select the jobs that feed group computations.

Response

Field	Type	Description
`group_id`	string	The group listed.
`total_jobs`	integer	Jobs matching the filters.
`jobs`	array	Job metadata: `job_id`, `status`, `recorded_at`, `created_at`, `use_case`, `condition`, `audio_duration_seconds`.
`page`	integer	The page returned.
`total_pages`	integer	Total pages available.

Example

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"

const response = await fetch("https://api.amplifierhealth.com/v2/groups/daily-checkins/jobs?status=done", {
  headers: {
    "X-Account-ID": process.env.AMPLIFIER_ACCOUNT_ID,
    "X-API-Key": process.env.AMPLIFIER_API_KEY,
  },
});

const data = await response.json();

# Requires httpx: pip install httpx
import os
import httpx

response = httpx.get(
  "https://api.amplifierhealth.com/v2/groups/daily-checkins/jobs?status=done",
  headers={
      "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"],
      "X-API-Key": os.environ["AMPLIFIER_API_KEY"],
  },
)

data = response.json()

Example response

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

Errors

HTTP	Condition
400	`from` or `to` is not a valid ISO 8601 datetime.
404	No group with this `group_id` exists for your account.

Add jobs to a group

POST /v2/groups/{group_id}/jobs

Add jobs you have already submitted into a group.

Use this to backfill a group from existing jobs. To register a job into a group at submission time instead, use analyze-into-a-group on the Longitudinal API.

Each job_id is handled independently and reported in exactly one of added, skipped, or not_found — a job id that isn’t found leaves the rest of the batch unaffected, and the request still returns 200.

Path Parameters

Parameter	Type	Description
`group_id`	string	The group to add jobs to.

Request Body

Requests use Content-Type: application/json.

Field	Type	Required	Description
`job_ids`	string[]	Yes	Job IDs to add. Between 1 and 100 per request.

Response

Field	Type	Description
`status`	string	Always `"accepted"`.
`added`	string[]	Job IDs added to the group.
`skipped`	object	Job ID to reason, for jobs already in the group (`"already_in_group"`).
`not_found`	string[]	Job IDs that don’t exist for your account.
`not_yet_done`	string[]	Added jobs that are still `queued` or `running`. They contribute to group computations once they reach `done`. This is a subset of `added`.

Example

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

const response = await fetch("https://api.amplifierhealth.com/v2/groups/daily-checkins/jobs", {
  method: "POST",
  headers: {
    "X-Account-ID": process.env.AMPLIFIER_ACCOUNT_ID,
    "X-API-Key": process.env.AMPLIFIER_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "job_ids": [
      "job_ddd",
      "job_eee",
      "job_fff",
      "job_ggg",
      "job_hhh"
    ]
  }),
});

const data = await response.json();

# Requires httpx: pip install httpx
import os
import httpx

response = httpx.post(
  "https://api.amplifierhealth.com/v2/groups/daily-checkins/jobs",
  headers={
      "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"],
      "X-API-Key": os.environ["AMPLIFIER_API_KEY"],
  },
  json={
    "job_ids": [
      "job_ddd",
      "job_eee",
      "job_fff",
      "job_ggg",
      "job_hhh",
    ],
  },
)

data = response.json()

Example response

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

Errors

HTTP	Condition
400	`GROUP_VERSION_MISMATCH`: one or more jobs ran on a different model version than the group. The `message` is `model_version does not match the group's model version; jobs: <job_id>, <job_id>`. Nothing is added. See Model versions.
404	No group with this `group_id` exists for your account.

Remove a job from a group

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

Remove a job from a group. The job itself is kept.

Removing a job clears the group’s stored longitudinal and aggregate results, so the next read recomputes them without that job.

Path Parameters

Parameter	Type	Description
`group_id`	string	The group to remove from.
`job_id`	string	The job to remove.

Example

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"

const response = await fetch("https://api.amplifierhealth.com/v2/groups/daily-checkins/jobs/job_bbb", {
  method: "DELETE",
  headers: {
    "X-Account-ID": process.env.AMPLIFIER_ACCOUNT_ID,
    "X-API-Key": process.env.AMPLIFIER_API_KEY,
  },
});

const data = await response.json();

# Requires httpx: pip install httpx
import os
import httpx

response = httpx.delete(
  "https://api.amplifierhealth.com/v2/groups/daily-checkins/jobs/job_bbb",
  headers={
      "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"],
      "X-API-Key": os.environ["AMPLIFIER_API_KEY"],
  },
)

data = response.json()

Example response

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

Errors

HTTP	Condition
404	The group, or this job’s membership in it, does not exist.

Errors

HTTP	Condition
400	`group_id` is empty, too long, or contains unsupported characters (`POST /v2/groups`); or `from`/`to` is not a valid ISO 8601 datetime.
404	The group, job, or membership does not exist for your account, or a `group_id` in the path is malformed.
409	`POST /v2/groups` was called with a `group_id` that already exists.

For authentication and retry guidance, see Errors.

Longitudinal API — raw analyze into a group, longitudinal analyze, trajectory, and aggregate.
Longitudinal concepts — groups, baselines, deviation, trend, and the history window as concepts.
Jobs API — read a job by ID after you list it in a group.