---
title: Groups API
description: Create groups and manage job membership.
type: doc
icon: users
sidebar:
  label: Groups API
  order: 7
  icon: users
search:
  tags: [api]
---
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](/reference/longitudinal-api). Concepts (`recorded_at`, history window): [Longitudinal concepts](/guides/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 `.` `_` `~` `:` `-` |

### 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. |
| `created_at` | string | ISO 8601 creation timestamp. |

### Example

<CodeGroup param="lang">

```bash cURL
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"}'
```

```javascript JavaScript
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"
  }),
});

const data = await response.json();
```

```python Python
# 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",
  },
)

data = response.json()
```

</CodeGroup>

### Example response

```json
{
  "group_id": "daily-checkins",
  "job_count": 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. |

## 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. |
| `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

<CodeGroup param="lang">

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

```javascript JavaScript
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();
```

```python Python
# 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()
```

</CodeGroup>

### Example response

```json
{
  "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 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}`](/reference/jobs#retrieve-a-job). 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

<CodeGroup param="lang">

```bash cURL
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"
```

```javascript JavaScript
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();
```

```python Python
# 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()
```

</CodeGroup>

### Example response

```json
{ "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}`](/reference/jobs#retrieve-a-job).

### 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

<CodeGroup param="lang">

```bash cURL
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"
```

```javascript JavaScript
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();
```

```python Python
# 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()
```

</CodeGroup>

### Example response

```json
{
  "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](/reference/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

<CodeGroup param="lang">

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

```javascript JavaScript
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();
```

```python Python
# 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()
```

</CodeGroup>

### Example response

```json
{
  "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 |
|---|---|
| 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

<CodeGroup param="lang">

```bash cURL
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"
```

```javascript JavaScript
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();
```

```python Python
# 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()
```

</CodeGroup>

### Example response

```json
{ "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](/reference/errors#error-codes).

## Related pages

- [Longitudinal API](/reference/longitudinal-api) — raw analyze into a group, longitudinal analyze, trajectory, and aggregate.
- [Longitudinal concepts](/guides/longitudinal) — groups, baselines, deviation, trend, and the history window as concepts.
- [Jobs API](/reference/jobs) — read a job by ID after you list it in a group.