---
title: "List project end-users with usage metrics"
method: GET
path: "/v1/projects/{projectSlug}/users"
tags: ["Users"]
---

# List project end-users with usage metrics

`GET /v1/projects/{projectSlug}/users`

Returns a page of the project's identified end-users over the range, each with trace, session, token, and cost metrics, plus cost aggregates across every matching user. The range defaults to the trailing 30 days.

## Path parameters

- `projectSlug` string, required — Project slug (human-readable identifier)

## Query parameters

- `fromIso` string, date-time — Lower bound (inclusive) of the time range. Defaults to 30 days before `toIso`.
- `toIso` string, date-time — Upper bound (inclusive) of the time range. Defaults to now.
- `limit` integer — Page size. Max 100.
- `offset` integer, nullable — Zero-based offset of the first user to return.
- `sortBy` 'lastSeen' | 'firstSeen' | 'traces' | 'sessions' | 'errors' | 'tokens' | 'cost' | 'costAvg' | 'costMedian' — Field to sort by. Defaults to most recently seen.
- `sortDirection` 'asc' | 'desc' — Sort direction. Defaults to descending.
- `searchQuery` string — Case-insensitive substring match on the user's id or email.

## Response `200`

Page of end-users

- UserListResponse
  - `items` ProjectUser[], required — Page of users, in the requested sort order.
    - `userId` string, required — The end-user's identifier, as reported on their traces' `user_id`.
    - `userEmail` string, required — Latest non-empty email seen on the user's traces. Empty when never reported.
    - `firstSeenAt` string, required — ISO-8601 timestamp of the user's first trace in the range.
    - `lastSeenAt` string, required — ISO-8601 timestamp of the user's most recent trace in the range.
    - `traceCount` integer, required — Traces attributed to the user in the range.
    - `sessionCount` integer, required — Distinct sessions in which the user produced at least one trace.
    - `errorSessionCount` integer, required — Of `sessionCount`, sessions with at least one errored trace.
    - `tokensTotal` integer, required — Total tokens across the user's traces.
    - `costTotalMicrocents` number, required — Total cost across the user's traces, in microcents.
    - `costAvgMicrocents` number, required — Mean per-trace cost across the user's traces, in microcents.
    - `costMedianMicrocents` number, required — Median (p50) per-trace cost across the user's traces, in microcents.
  - `totalCount` integer, required — Total users matching the filters across every page.
  - `hasMore` boolean, required — `true` when there is at least one more page after this one.
  - `limit` integer, required — Page size used for this response.
  - `offset` integer, required — Zero-based offset of the first item in this page.
  - `costRollup` UserCostRollup, required — Cost aggregates across every matching user, not just this page.
    - `sum` number, required — Sum of every matching user's total cost, in microcents.
    - `avg` number, required — Mean of every matching user's mean per-trace cost, in microcents.
    - `median` number, required — Median of every matching user's median per-trace cost, in microcents.

## Other responses

- `400` — Validation error
- `401` — Unauthorized
- `404` — Not found

---

[API](https://skmtc.net/latitude-dev/apis/latitude.md) · [All operations](https://skmtc.net/latitude-dev/apis/latitude/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/latitude-dev/latitude/versions/6a8789c59a5c/schema)