People

List the people of a MIRA FIVE project with views, segments and person filters, and read one person's profile by ref.

A person is someone the site recognised with consent: a signed-in user, or a browser in full mode. List them as the People screen does, or read one profile by its ref. Traffic collected without consent never becomes people: on such a project the list is empty and meta.availability says why.

List people

GET /api/v1/projects/{project_id}/people

People active in the period, 50 per page.

Name	Type	Default	Description
`period`	string	`30d`	`1h`, `24h`, `7d`, `30d`, `90d`, `12m` or `custom`. See Periods.
`from`	string	none	First day of a custom period, `YYYY-MM-DD`. Required with `period=custom`.
`to`	string	none	Last day of a custom period, inclusive. Required with `period=custom`.
`view`	string	`everyone`	`everyone`; `customers` (bought); `known` (signed in); `high-intent` (showed intent, not bought).
`sort`	string	`last_seen`	`last_seen`, `first_seen`, `value` (revenue in the reporting currency) or `visits`. Always descending.
`window`	string	none	`all` lists everyone in the retained history instead of the period. Slower.
`new`	string	none	`1` keeps only people first seen in the period.
`segment`	string	none	A saved segment's id. Keeps only its members.
`filters[i][field]`, `filters[i][op]`, `filters[i][value]`	string	none	Person filters, all of which must hold. At most 12.
`cursor`	string	none	`meta.nextCursor` of the previous page. A cursor belongs to one `sort`.

compare is refused.

curl -G https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/people \
  -H "Authorization: Bearer $MIRAFIVE_API_KEY" \
  --data-urlencode 'view=customers' \
  --data-urlencode 'sort=value' \
  --data-urlencode 'filters[0][field]=first_channel' \
  --data-urlencode 'filters[0][op]=is' \
  --data-urlencode 'filters[0][value]=organic_search'

200 OK

{
  "data": [
    {
      "id": "0196f0a1-2b3c-7d4e-8f5a-6b7c8d9e0f1a",
      "type": "people",
      "attributes": {
        "name": "Lena Hoffmann",
        "known": true,
        "stage": "customer",
        "firstSeen": "2026-06-14T19:02:11.540+02:00",
        "lastSeen": "2026-09-26T21:47:30.118+02:00",
        "visits": 6,
        "value": [{ "currency": "EUR", "amount": 412.7 }],
        "firstTouch": {
          "channel": "organic_search",
          "source": "google.com",
          "campaign": "",
          "landing": "/products/linen-shirt"
        },
        "country": "DE",
        "device": "desktop",
        "lastPath": "/checkout/thank-you"
      },
      "links": {
        "self": "https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/people/0196f0a1-2b3c-7d4e-8f5a-6b7c8d9e0f1a"
      }
    },
    {
      "id": "01970b2c-3d4e-7f5a-9b6c-7d8e9f0a1b2c",
      "type": "people",
      "attributes": {
        "name": "u_58213",
        "known": true,
        "stage": "customer",
        "firstSeen": "2026-08-30T08:15:42.003+02:00",
        "lastSeen": "2026-09-24T12:31:05.871+02:00",
        "visits": 3,
        "value": [{ "currency": "EUR", "amount": 129 }, { "currency": "CHF", "amount": 89 }],
        "firstTouch": {
          "channel": "organic_search",
          "source": "bing.com",
          "campaign": "",
          "landing": "/"
        },
        "country": "CH",
        "device": "mobile",
        "lastPath": "/account/orders"
      },
      "links": {
        "self": "https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/people/01970b2c-3d4e-7f5a-9b6c-7d8e9f0a1b2c"
      }
    }
  ],
  "links": {
    "self": "https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/people?view=customers&sort=value&filters%5B0%5D%5Bfield%5D=first_channel&filters%5B0%5D%5Bop%5D=is&filters%5B0%5D%5Bvalue%5D=organic_search",
    "next": null
  },
  "meta": {
    "period": {
      "preset": "30d",
      "from": "2026-08-29T00:00:00+02:00",
      "to": "2026-09-28T00:00:00+02:00",
      "timezone": "Europe/Berlin",
      "interval": "day",
      "comparison": null,
      "clampedToRetention": false
    },
    "allTime": false,
    "view": "customers",
    "sort": "value",
    "availability": "ready",
    "perPage": 50,
    "nextCursor": null
  }
}

Field	Type	Description
`id`	string	The person's ref, a UUID. Pass it to Get a person.
`attributes.name`	string or null	Their name from identify, or their user id when they gave no name. `null` for a visitor who never signed in.
`attributes.known`	boolean	Signed in at least once.
`attributes.stage`	string	`customer` (bought), `known` (signed in), `returning` (two visits or more) or `visitor`.
`attributes.firstSeen`, `attributes.lastSeen`	string	Their first and latest activity in the retained history.
`attributes.visits`	integer	Visits in the period.
`attributes.value`	array	Revenue per currency, `{ currency, amount }`, reporting currency first.
`attributes.firstTouch`	object or null	How they first came: `channel`, `source` (UTM source, else the referring host), `campaign` and `landing` path. Empty strings where nothing was tagged.
`attributes.country`	string	Two-letter country code.
`attributes.device`	string	`desktop`, `mobile` or `tablet`.
`attributes.lastPath`	string	The last page they viewed.
`links.self`	string	The person's profile in the API.
`meta.allTime`	boolean	Whether `window=all` was asked for.
`meta.view`, `meta.sort`	string	The view and sort used.
`meta.availability`	string	`ready`; `consentless_only` (the project collects without consent, so it has nobody to list); `no_sources` (the project has no source yet).
`meta.perPage`, `meta.nextCursor`		See Pagination.

Person filters

People take their own filters, not the event filters of reports. Each is filters[i][field], filters[i][op] and filters[i][value]; all must hold. At most 12, and value is at most 500 characters.

Field	Operators	Value
`stage`	`is`, `is_not`	`customer`, `known`, `returning` or `visitor`
`purchase`	`set` (made), `not_set` (not made)	none
`goal`	`is` (reached), `is_not` (not reached)	a goal id, from List goals
`action`	`is` (done), `is_not` (not done)	an action id
`segment`	`is`, `is_not`	a segment id
`funnel`	`is`	a step: `{window}:{step}:{reached or stopped}:{action id},{action id},…`, e.g. `7:2:stopped:<id>,<id>` for people who got to step 2 and no further
`experiment`	`is`	`{experiment id}:{a or b}`, optionally followed by `:goal` or `:purchase` for those who then reached the deciding goal or bought
`first_channel`, `last_channel`	`is`, `is_not`	a channel: `paid_search`, `paid_social`, `email`, `ai_assistant`, `organic_search`, `organic_social`, `campaign`, `referral`, `direct`
`first_campaign`, `last_campaign`	`is`, `is_not`, `contains`, `set`, `not_set`	a `utm_campaign`
`first_landing`, `last_landing`	`is`, `is_not`, `starts_with`, `contains`	a page path
`first_ad_platform`, `last_ad_platform`	`is`, `is_not`	`google_ads` or `meta_ads`
`country`	`is`, `is_not`	an upper-case two-letter code, e.g. `DE`
`device`	`is`, `is_not`	`desktop`, `mobile` or `tablet`

The first touch is the visit that first brought a person. The last touch is their latest visit from outside (not direct), else their latest visit. goal, action, purchase and funnel count within the period. Trait filters (traits.<key>) belong to segments and are refused here.

Get a person

GET /api/v1/projects/{project_id}/people/{ref}

One person over their whole retained history. ref comes from the list or from an event. The ref of a browser that later signed in answers with the person who claimed it, and id carries that person's ref.

curl https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/people/0196f0a1-2b3c-7d4e-8f5a-6b7c8d9e0f1a \
  -H "Authorization: Bearer $MIRAFIVE_API_KEY"

200 OK

{
  "data": {
    "id": "0196f0a1-2b3c-7d4e-8f5a-6b7c8d9e0f1a",
    "type": "people",
    "attributes": {
      "name": "Lena Hoffmann",
      "email": "lena.hoffmann@example.com",
      "userId": "u_40177",
      "known": true,
      "stage": "customer",
      "firstSeen": "2026-06-14T19:02:11.540+02:00",
      "lastSeen": "2026-09-26T21:47:30.118+02:00",
      "visits": 14,
      "activeDays": 11,
      "events": 236,
      "pageviews": 181,
      "orders": 3,
      "revenue": [{ "currency": "EUR", "amount": 412.7 }],
      "firstTouch": {
        "channel": "organic_search",
        "source": "google.com",
        "campaign": "",
        "landing": "/products/linen-shirt"
      },
      "client": {
        "country": "DE",
        "region": "HH",
        "device": "desktop",
        "browser": "Firefox",
        "os": "macOS",
        "locale": "de-DE"
      },
      "traits": [
        { "key": "plan", "value": "club" },
        { "key": "newsletter", "value": "true" }
      ],
      "browsers": 2,
      "sharedBrowser": false
    },
    "links": {
      "self": "https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/people/0196f0a1-2b3c-7d4e-8f5a-6b7c8d9e0f1a"
    }
  }
}

It takes no query parameters except sparse fieldsets. A ref the project does not know gets 404 with Nobody with this ref within what the plan keeps, or they were erased.

Field	Type	Description
`id`	string	The person's current ref.
`attributes.name`, `attributes.email`, `attributes.userId`	string or null	What they signed in with, from identify. `null` when never given.
`attributes.known`	boolean	Whether they have a user id.
`attributes.stage`	string	`customer`, `known`, `returning` or `visitor`.
`attributes.firstSeen`, `attributes.lastSeen`	string	First and latest activity.
`attributes.visits`, `attributes.activeDays`, `attributes.events`, `attributes.pageviews`, `attributes.orders`	integer	Counts over the retained history.
`attributes.revenue`	array	Revenue per currency, `{ currency, amount }`.
`attributes.firstTouch`	object or null	`channel`, `source`, `campaign`, `landing` of the visit that first brought them.
`attributes.client`	object	`country`, `region` (ISO subdivision code), `device`, `browser`, `os` and `locale`.
`attributes.traits`	array	`{ key, value }` of their latest identify traits.
`attributes.browsers`	integer	How many browsers are joined to this person.
`attributes.sharedBrowser`	boolean	Someone else signed in on one of their browsers.
`links.self`	string	This profile's URL in the API.

List peopleCopy Anchor Link

Person filtersCopy Anchor Link

Get a personCopy Anchor Link

On this page

List people

Person filters

Get a person