Get Logs - Unify Documentation

GET

logs

curl --request GET \
  --url 'https://api.unify.ai/v0/logs?project=eval-project&column_context=subjects/science/physics&context=training&return_versions=None&group_threshold=None&value_limit=None&filter_expr=len(output)%20>%20200%20and%20temperature%20==%200.5&sorting={'timestamp':%20'descending',%20'round(score,%202)':%20'ascending'}&group_sorting={'entries/student':%20{'field':%20'score',%20'direction':%20'descending',%20'metric':%20'mean'}}&from_ids=0&1&2&exclude_ids=0&1&2&from_fields=score&response&exclude_fields=score&response&limit=None&offset=None&group_by=['model',%20'temperature']&group_limit=None&group_offset=None&group_depth=None&nested_groups=None&groups_only=None&return_timestamps=None&return_ids_only=None&randomize=None&seed=None' \
  --header "Authorization: Bearer $UNIFY_KEY"

{
    "params": {},
    "logs": [
        {
            "id": "0",
            "ts": "2024-10-30 12:20:03",
            "entries": {
                "key1": "a",
                "key2": 1.0
            },
            "derived_entries": {},
            "params": {}
        },
        {
            "id": "1",
            "ts": "2024-10-30 12:22:14",
            "entries": {
                "key1": "b",
                "key2": 2.0
            },
            "derived_entries": {},
            "params": {}
        }
    ],
    "count": 2
}

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.
- If return_versions is also True, returns a list of objects with both id and version information.
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.

If return_versions=True:

Returns all versions of logs in versioned contexts
from_ids and exclude_ids must be provided as lists of objects with ‘id’ and ‘version’ keys
Each object must have format: {"id": log_event_id, "version": version_number}
This is only valid for logs in versioned contexts

If return_versions=False (default):

Returns only the latest version of each log
from_ids and exclude_ids should be strings of ’&‘-separated log event IDs

Authorizations

Authorization

string

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

project

string

required

Name of the project to get entries from.

column_context

string | null

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

context

string | null

Static context to filter logs by.

return_versions

boolean

default:"false"

Whether to return all versions of logs. Only valid for versioned contexts.

group_threshold

integer | null

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

value_limit

integer | null

Maximum number of characters to return for string values.

filter_expr

string | null

Boolean string to filter entries. TODO: Detailed page.

sorting

string | null

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 | null

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

from_ids

any | null

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.

exclude_ids

any | null

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_fields

string | null

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 | null

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 | null

offset

integer

default:"0"

group_by

array | null

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

group_limit

integer | null

Maximum number of groups to return at each level

group_offset

integer

default:"0"

Number of groups to skip at each level

group_depth

integer | null

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

nested_groups

boolean

default:"true"

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

groups_only

boolean

default:"false"

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

return_timestamps

boolean

default:"false"

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

default:"false"

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

randomize

boolean

default:"false"

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

seed

string | null

default:"42"

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

curl --request GET \
  --url 'https://api.unify.ai/v0/logs?project=eval-project&column_context=subjects/science/physics&context=training&return_versions=None&group_threshold=None&value_limit=None&filter_expr=len(output)%20>%20200%20and%20temperature%20==%200.5&sorting={'timestamp':%20'descending',%20'round(score,%202)':%20'ascending'}&group_sorting={'entries/student':%20{'field':%20'score',%20'direction':%20'descending',%20'metric':%20'mean'}}&from_ids=0&1&2&exclude_ids=0&1&2&from_fields=score&response&exclude_fields=score&response&limit=None&offset=None&group_by=['model',%20'temperature']&group_limit=None&group_offset=None&group_depth=None&nested_groups=None&groups_only=None&return_timestamps=None&return_ids_only=None&randomize=None&seed=None' \
  --header "Authorization: Bearer $UNIFY_KEY"

{
    "params": {},
    "logs": [
        {
            "id": "0",
            "ts": "2024-10-30 12:20:03",
            "entries": {
                "key1": "a",
                "key2": 1.0
            },
            "derived_entries": {},
            "params": {}
        },
        {
            "id": "1",
            "ts": "2024-10-30 12:22:14",
            "entries": {
                "key1": "b",
                "key2": 2.0
            },
            "derived_entries": {},
            "params": {}
        }
    ],
    "count": 2
}

Delete Logs Update Derived Log

curl --request GET \
  --url 'https://api.unify.ai/v0/logs?project=eval-project&column_context=subjects/science/physics&context=training&return_versions=None&group_threshold=None&value_limit=None&filter_expr=len(output)%20>%20200%20and%20temperature%20==%200.5&sorting={'timestamp':%20'descending',%20'round(score,%202)':%20'ascending'}&group_sorting={'entries/student':%20{'field':%20'score',%20'direction':%20'descending',%20'metric':%20'mean'}}&from_ids=0&1&2&exclude_ids=0&1&2&from_fields=score&response&exclude_fields=score&response&limit=None&offset=None&group_by=['model',%20'temperature']&group_limit=None&group_offset=None&group_depth=None&nested_groups=None&groups_only=None&return_timestamps=None&return_ids_only=None&randomize=None&seed=None' \
  --header "Authorization: Bearer $UNIFY_KEY"

{
    "params": {},
    "logs": [
        {
            "id": "0",
            "ts": "2024-10-30 12:20:03",
            "entries": {
                "key1": "a",
                "key2": 1.0
            },
            "derived_entries": {},
            "params": {}
        },
        {
            "id": "1",
            "ts": "2024-10-30 12:22:14",
            "entries": {
                "key1": "b",
                "key2": 2.0
            },
            "derived_entries": {},
            "params": {}
        }
    ],
    "count": 2
}

​Authorizations

​Query Parameters

Authorizations

Query Parameters