v1

latestOpenAPI 3.1.02026-07-13154170539.0 KB

Logs

Get Logs

Returns a list of filtered log entries from a project with various expressiveness options:

Monolithic mode (when group_by is not provided):
- Returns a flat list of log entries (with fields clipped if value_limit is set).
- Optionally factors out repeated fields into a grouped_entries field if group_threshold is set.
Grouped mode (when group_by is provided):
- Supports multi-level grouping of logs. The order of fields in group_by dictates the nesting order.
- Supports pagination at the group level using group_limit and group_offset.
- Supports limiting the nesting depth with group_depth.
- When nested_groups is True, returns a nested structure under the "logs" key.
- When nested_groups is False, returns flat per-field mappings under the "groups" key.
- When groups_only is True, the detailed log objects are omitted and leaves are simplified to either lists of log ids (if return_timestamps is False) or mappings of {log id: timestamp} (if True).
Return IDs only mode:
- If return_ids_only is True, returns only the log event ids.
Dynamic expression sorting:
- In addition to static field-based sorting, you can use dynamic expressions for sorting.
- The same grammar supported for filter_expr applies to sorting expressions.

The response always includes:

params: The parameter versions used across the logs.
count: The total number of logs matching the query.
Additionally, it includes either logs (in monolithic or nested grouping mode) or groups (in flat grouping mode) as specified by the arguments.

get/v0/logs

Query parameters

project_namestring required

Name of the project to get entries from.

column_contextstring nullable

The context (prepending '/' seperated field names) from which to retrieve the logs.

contextstring nullable

Static context to filter logs by.

group_thresholdinteger nullable

When set, entries that appear in at least this many logs will be grouped together.

value_limitinteger nullable

Maximum number of characters to return for string values.

filter_exprstring nullable

Boolean string to filter entries.

sortingstring nullable

JSON-encoded dict mapping either static column names (e.g. timestamp) or full Python2SQL expressions (e.g. cosine(embed('search text'), embedding_vector)) to sort directions ("ascending" or "descending"). The first key is the primary sort field; subsequent keys break ties.

group_sortingstring nullable

Sorting configuration for groups when using group_by. Specifies how to sort groups relative to each other based on aggregated metrics.

{"stackTrail":"paths:/v0/logs:get:parameters:8:schema:anyOf","oasType":"schema","type":"unknown","title":"From Ids","description":"The log ids which are permitted to be included in the search. Each log id listed does not need to be returned, but no logs which are not included in this list can be returned. This argument *cannot* be set if `exclude_ids` is set.","nullable":true}

The log ids which are permitted to be included in the search. Each log id listed does not need to be returned, but no logs which are not included in this list can be returned. This argument cannot be set if exclude_ids is set.

{"stackTrail":"paths:/v0/logs:get:parameters:9:schema:anyOf","oasType":"schema","type":"unknown","title":"Exclude Ids","description":"The log ids which cannot be returned from the search. None of the listed ids will be returned, even if the logs are valid as per the filtering expression etc. This argument *cannot* be set if `from_ids` is set.","nullable":true}

The log ids which cannot be returned from the search. None of the listed ids will be returned, even if the logs are valid as per the filtering expression etc. This argument cannot be set if from_ids is set.

from_fieldsstring nullable

The fields which are permitted to be included in the search. Each field listed does not need to be returned, but no fields which are not included in this list can be returned. This argument cannot be set if exclude_fields is set.

exclude_fieldsstring nullable

The fields which cannot be returned from the search. None of the listed fields will be returned, even if the fields are valid as per the filtering expression etc. This argument cannot be set if from_fields is set.

limitinteger nullable

offsetinteger

group_bystring[] nullable

List of fields to group results by. Results will be nested based on these fields.

group_limitinteger nullable

Maximum number of groups to return at each level

group_offsetinteger

Number of groups to skip at each level

group_depthinteger nullable

Maximum depth of nested groups to return. If not specified, all levels are returned.

nested_groupsboolean

If True, groups are returned as a nested structure; if False, groups are returned as flat per-field mappings.

groups_onlyboolean

If True, do not include a full logs list; only return groups (with leaf values being either log ids or timestamps).

return_timestampsboolean

When groups_only is True, return each leaf as a mapping from log id to timestamp instead of just a list of log ids.

return_ids_onlyboolean

If True, return only log IDs instead of full entries.

randomizeboolean

If true, return logs in a deterministic random order (fixed seed) instead of newest-first.

seedstring nullable

If provided, use this seed for deterministic random ordering instead of the default.

Response

Successful Response

{"stackTrail":"paths:/v0/logs:get:responses:200:content:application/json:schema","oasType":"schema","type":"unknown"}