---
title: "Get Logs"
method: GET
path: "/v0/logs"
tags: ["Logs"]
---

# Get Logs

`GET /v0/logs`

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

  1. **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.

  2. **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).

  3. **Return IDs only mode**:
     - If return_ids_only is True, returns only the log event ids.

  4. **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.

## Query parameters

- `project_name` string, required — Name of the project to get entries from.
- `column_context` string, nullable — The context (prepending '/' seperated field names) from which to retrieve the logs.
- `context` string, nullable — Static context to filter logs by.
- `group_threshold` integer, nullable — When set, entries that appear in at least this many logs will be grouped together.
- `value_limit` integer, nullable — Maximum number of characters to return for string values.
- `filter_expr` string, nullable — Boolean string to filter entries.
- `sorting` string, 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_sorting` string, nullable — Sorting configuration for groups when using group_by. Specifies how to sort groups relative to each other based on aggregated metrics.
- `from_ids` unknown
- `exclude_ids` unknown
- `from_fields` string, 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_fields` string, 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.
- `limit` integer, nullable
- `offset` integer
- `group_by` string[], nullable — List of fields to group results by. Results will be nested based on these fields.
- `group_limit` integer, nullable — Maximum number of groups to return at each level
- `group_offset` integer — Number of groups to skip at each level
- `group_depth` integer, nullable — Maximum depth of nested groups to return. If not specified, all levels are returned.
- `nested_groups` boolean — If True, groups are returned as a nested structure; if False, groups are returned as flat per-field mappings.
- `groups_only` boolean — If True, do not include a full logs list; only return groups (with leaf values being either log ids or timestamps).
- `return_timestamps` boolean — 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_only` boolean — If True, return only log IDs instead of full entries.
- `randomize` boolean — If true, return logs in a deterministic random order (fixed seed) instead of newest-first.
- `seed` string, nullable — If provided, use this seed for deterministic random ordering instead of the default.

## Response `200`

Successful Response

- unknown

## Other responses

- `404` — Project Not Found
- `422` — Validation Error

---

[API](https://skmtc.net/unify/apis/unifyai-http-api-reference.md) · [All operations](https://skmtc.net/unify/apis/unifyai-http-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/unify/unifyai-http-api-reference/revisions/900377f918b6/schema)