Skip to content

Cohorts API

List, create and update cohorts, and read the persons in them, through the API.

A cohort is a group of persons. A dynamic cohort is defined by filters and updates itself as people match or stop matching. A static cohort is a fixed list of persons that only changes when you add or remove them.

Reading needs a personal API key with cohort:read; creating and changing cohorts needs cohort:write. Listing a cohort's persons also needs person:read.

List cohorts

GET /api/projects/<project ID>/cohorts/
bash
curl https://app.myjourneyanalytics.com/api/projects/12345/cohorts/ \
  -H "Authorization: Bearer <personal API key>"

Results are paged; see pagination. Each cohort has an id, name, filters, is_static and a count of persons.

Get one cohort

GET /api/projects/<project ID>/cohorts/<cohort ID>/

The cohort ID is the number in the cohort's address in the app.

Create a dynamic cohort

This cohort contains everyone whose email property contains @example.com:

bash
curl -X POST https://app.myjourneyanalytics.com/api/projects/12345/cohorts/ \
  -H "Authorization: Bearer <personal API key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example staff",
    "filters": {
      "properties": {
        "type": "OR",
        "values": [
          {
            "type": "AND",
            "values": [
              { "key": "email", "type": "person", "operator": "icontains", "value": "@example.com" }
            ]
          }
        ]
      }
    }
  }'

Groups in the outer OR are alternatives; conditions inside an AND group must all match.

In the app, building cohorts from what people did, such as "performed an event in the last 30 days", needs Behavioural cohorts on your plan. The easiest way to get the right filters for a complex cohort is to build it in the app, then read it back with the API and copy its filters.

Create a static cohort

Create the cohort with is_static, then add persons by their UUIDs:

bash
curl -X POST https://app.myjourneyanalytics.com/api/projects/12345/cohorts/ \
  -H "Authorization: Bearer <personal API key>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Beta testers", "is_static": true }'
bash
curl -X PATCH https://app.myjourneyanalytics.com/api/projects/12345/cohorts/<cohort ID>/add_persons_to_static_cohort/ \
  -H "Authorization: Bearer <personal API key>" \
  -H "Content-Type: application/json" \
  -d '{ "person_ids": ["<person UUID>", "<person UUID>"] }'

To take one person out again:

bash
curl -X PATCH https://app.myjourneyanalytics.com/api/projects/12345/cohorts/<cohort ID>/remove_person_from_static_cohort/ \
  -H "Authorization: Bearer <personal API key>" \
  -H "Content-Type: application/json" \
  -d '{ "person_id": "<person UUID>" }'

Find person UUIDs with the persons API.

Update a cohort

Send only the fields you want to change:

bash
curl -X PATCH https://app.myjourneyanalytics.com/api/projects/12345/cohorts/<cohort ID>/ \
  -H "Authorization: Bearer <personal API key>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Example staff (all offices)" }'

Delete a cohort

Cohorts are not deleted with DELETE, which returns 405. Mark them deleted instead:

bash
curl -X PATCH https://app.myjourneyanalytics.com/api/projects/12345/cohorts/<cohort ID>/ \
  -H "Authorization: Bearer <personal API key>" \
  -H "Content-Type: application/json" \
  -d '{ "deleted": true }'

List the persons in a cohort

GET /api/projects/<project ID>/cohorts/<cohort ID>/persons/
js
const res = await fetch(
  "https://app.myjourneyanalytics.com/api/projects/12345/cohorts/42/persons/",
  { headers: { Authorization: `Bearer ${process.env.MJ_PERSONAL_API_KEY}` } },
);
const { results, next } = await res.json();

Follow next to read further pages. Add ?format=csv to download the list as CSV instead.

A dynamic cohort's members are recalculated in the background, so persons who only just started matching may take a little while to appear.

Can't find what you need? Contact support