Skip to main content
POST
Error

Authorizations

X-API-Key
string
header
required
X-Tenant-Id
string
header
required

Body

application/json
project_id
string<uuid>
required

ProjectID identifies the tracing project whose users to query.

cursor
string

Cursor continues recent-user discovery with state independent of the number of users already returned. The activity window stays fixed, but changes to matching activity can cause skipped or repeated users. Maximum encoded length is 65536 bytes.

Maximum string length: 65536
filter
string

Filter narrows which completed root runs count toward a user, using a LangSmith filter expression evaluated against each root run; users with no matching root run are not returned. For example: eq(status, "error"). See https://docs.langchain.com/langsmith/trace-query-syntax#filter-query-language for syntax.

Example:

"eq(status, \"error\")"

max_start_time
string<date-time>

MaxStartTime is an exclusive upper bound on root start time; defaults to the current time on the first page. Continuation preserves the original window.

min_start_time
string<date-time>

MinStartTime is an inclusive lower bound on root start time; defaults to seven days before max_start_time. The window must not exceed 31 days.

page_size
integer
default:20

Limit sets the page size. Changing it preserves the cursor's position and activity window.

Required range: 1 <= x <= 100
stats_wait_ms
integer

StatsWaitMs limits how long the request waits for user statistics. When the limit passes, users are returned with stats_status=pending; fetch their statistics with /v2/runs/users/stats. Omit to wait for statistics until the request deadline.

Required range: 1 <= x <= 60000
trace_filter
string

TraceFilter restricts the traces used to discover users and compute their statistics. Project and trace access restrictions always apply.

Response

OK

is_partial
boolean
required

IsPartial is true when discovery reaches its work limit before filling the requested page. A full page can have is_partial=false and a non-null next_cursor. Always use next_cursor to determine whether to continue, including after an empty partial page. Available statistics for returned users cover the entire requested window. Missing statistics are indicated by each user's stats_status, not is_partial.

items
object[]
required
next_cursor
string | null
required