Identity metrics

Identity metrics provide stored counts of anonymous and recognized identities in the current workspace.

The total count is anonymous + recognized.

Metrics are updated automatically after a successful source import or when you call the refresh endpoint. Retrieving stored metrics doesn't query the data warehouse.

Get daily identity metrics

Returns daily identity counts from start up to, but not including, end, ordered by UTC date.

Each day uses the latest observation recorded for that day. If no new observation is available, the most recent earlier counts are carried forward. Days before the first observation for the selected scope are omitted.

The requested interval must not exceed 60,000 days.

By default, the response contains workspace totals. Use connection to retrieve counts for one connection or the combined contribution of deleted connections.

Request

  • :start

    date Required

    The first UTC date to include, in YYYY-MM-DD format. It must be earlier than end and no earlier than 1970-01-01.

  • :end

    date Required

    The first UTC date not to include, in YYYY-MM-DD format. It must be later than start, no later than 2262-04-11, and no later than the day after the current UTC date.

  • connection

    string

    The connection ID, or deleted to return the combined counts for connections that no longer exist. Omit this parameter for workspace totals. Only one value is allowed.

    The ID must belong to the current workspace. Deleted connection IDs return 404 Not Found.

    The deleted counts are calculated from stored workspace totals minus the counts of connections that still exist when you make the request. Deleting a connection can therefore change this aggregate for earlier dates.

    For example, if a July 27 snapshot contains 100 identities from connection A and 50 from connection B, deleting B makes connection=deleted return 50 identities for that day.

    It cannot be longer than 12 characters.

Response

A zero count represents an observed zero. If no counts are known for the requested interval, the response is an empty array.

In the example, the first observation is on July 27, so the preceding days are omitted.

The response is an array of objects with the following properties:

  • day

    date

    The UTC day represented by this entry, in YYYY-MM-DD format.

  • total

    64 bit int

    The total number of identities for this day and scope. It is the sum of anonymous and recognized.

  • anonymous

    64 bit int

    The number of anonymous identities for this day and scope.

  • recognized

    64 bit int

    The number of recognized identities for this day and scope.
GET /v1/metrics/identities/dates/:start/:end
curl https://example.com/v1/metrics/identities/dates/2026-07-24/2026-07-28 \
-H "Authorization: Bearer api_xxxxxxx"
Response
[
  {
    "day": "2026-07-27",
    "total": 420,
    "anonymous": 120,
    "recognized": 300
  }
]
Errors
401
Authorization header is missing or invalid
400
only one 'connection' parameter is allowed
400
value "invalid" is neither a valid connection identifier nor "deleted"
400
requested metrics exceed the maximum: 60001 days is more than 60,000
404
workspace does not exist
404
connection does not exist
404
start is not valid
404
end is not valid
404
start date is too far in the past
404
end date is too far in the future
404
day of the end date must be after the day of the start date
422
organization is disabled

Get latest identity metrics

Returns the latest stored identity counts for the current workspace, including a breakdown by source connection.

The connections array includes all existing source connections, ordered by connection ID. Connections with no counts in the latest snapshot have zero values.

Deleted connections are excluded from the breakdown, but their identities may still contribute to workspace totals. The sum of the connection counts can therefore be lower than the workspace totals.

Request

No parameters.

Response

Workspace creation records an initial snapshot with zero counts. If no snapshot exists, the endpoint returns 404 Not Found.

  • observedAt

    datetime

    The UTC timestamp of the snapshot. For a refresh, it is captured immediately before reading the counts from the data warehouse. For the initial zero snapshot, it is the workspace creation timestamp.

  • total

    64 bit int

    The total number of identities in the workspace. It is the sum of anonymous and recognized.

  • anonymous

    64 bit int

    The number of anonymous identities in the workspace.

  • recognized

    64 bit int

    The number of recognized identities in the workspace.

  • withoutProfile

    64 bit int

    The number of identities that aren't assigned to a profile. These identities can be anonymous or recognized and are already included in total.

  • connections

    array of object

    The identity counts for each source connection. This field is always present and is an empty array when there are no source connections. For each connection, the total is anonymous + recognized.

    • connection

      string

      The source connection ID.

    • anonymous

      64 bit int

      The number of anonymous identities for the connection.

    • recognized

      64 bit int

      The number of recognized identities for the connection.

    • withoutProfile

      64 bit int

      The number of identities for the connection that are not assigned to a profile. They may be anonymous or recognized and are already included in those counts.
GET /v1/metrics/identities/latest
curl https://example.com/v1/metrics/identities/latest \
-H "Authorization: Bearer api_xxxxxxx"
Response
{
  "observedAt": "2026-07-27T09:42:51Z",
  "total": 420,
  "anonymous": 120,
  "recognized": 300,
  "withoutProfile": 35,
  "connections": [
    {
      "connection": "2nT6w5FbK8mR",
      "anonymous": 45,
      "recognized": 120,
      "withoutProfile": 17
    },
    {
      "connection": "5FbK8mR3nT6w",
      "anonymous": 75,
      "recognized": 180,
      "withoutProfile": 18
    }
  ]
}
Errors
401
Authorization header is missing or invalid
404
workspace does not exist
422
organization is disabled

Refresh identity metrics

Reads the current identity counts from the workspace's data warehouse and updates the stored metrics. The request waits for the refresh to complete.

Send the request without a body. On success, the endpoint returns 200 OK with an empty response body.

Request

No parameters.

Response

No response body.
POST /v1/metrics/identities/refresh
curl -X POST https://example.com/v1/metrics/identities/refresh \
-H "Authorization: Bearer api_xxxxxxx"
Errors
401
Authorization header is missing or invalid
400
request body not allowed
404
workspace does not exist
422
data warehouse is in maintenance mode
422
organization is disabled
503
data warehouse cannot be accessed