List Agent Traces

POST

https://api.getzep.com/api/v4/agents/:agent_uuid/traces/list

POST

/api/v4/agents/:agent_uuid/traces/list

from zep_cloud import Zep
client = Zep(
    api_key="YOUR_API_KEY_HERE",
)
client.agent.trace.list(
    agent_uuid="agent_uuid",
)

{
  "items": [
    {
      "abandoned_at": "string",
      "agent_uuid": "string",
      "attempt_family_uuid": "string",
      "closed_at": "string",
      "created_at": "string",
      "internal": {
        "assertion_uuid": "string",
        "closing_sequence": 1,
        "current_summary_version": 1,
        "last_task_uuid": "string",
        "next_sequence": 1,
        "processing_state": "idle"
      },
      "learn_from": true,
      "learn_from_reason": "string",
      "metadata": {},
      "objective": "string",
      "outcome": "succeeded",
      "parent_trace_uuid": "string",
      "revision": 1,
      "source": {
        "connection_uuid": "string",
        "import_uuid": "string",
        "imported_at": "string",
        "kind": "trace_import",
        "provider": "string",
        "provider_project_id": "string",
        "run_uuid": "string",
        "scores": {},
        "source_changed": false,
        "source_revision": "string",
        "source_url": "string",
        "trace_ended_at": "string",
        "trace_id": "string",
        "trace_started_at": "string"
      },
      "status": "open",
      "task_family": "string",
      "task_family_inference": {
        "assigned_at": "string",
        "classifier_version": "string",
        "confidence": 1.1,
        "descriptor_version": 1,
        "learning_reusable": true,
        "state": "string"
      },
      "task_family_source": "string",
      "trace_id": "string",
      "updated_at": "string",
      "uuid": "string",
      "verification": "none"
    }
  ],
  "next_cursor": "string",
  "total_size": 1
}

Authentication

AuthorizationApi-Key

Type “Api-Key” followed by a space and the project API key.

Path parameters

agent_uuidstringRequired

Agent UUID

Query parameters

page_sizeintegerOptional1-100Defaults to 50

The maximum number of items in one page. The SDK method returns a pager. In Python, .items holds only the first page. In TypeScript, .data holds only the first page. To read every page, iterate the pager: use for or list(...) in Python, or for await in TypeScript. In Go, the method returns one page, and Iterator() reads all pages.

cursorstringOptional

Opaque page cursor

order_byenumOptional

Sort field

Allowed values:

orderenumOptional

asc or desc

Allowed values:

import_uuidstringOptional

Filter by owning Trace import UUID

source_kindenumOptional

Source kind

Allowed values:

Request

Filters

metadatamap from strings to anyOptional

Filters to Traces whose metadata contains these key-value pairs.

outcomeenumOptional

Filters to one reported outcome.

Allowed values:

parent_trace_uuidstringOptional

Filters to direct retries of this parent Trace.

statusenumOptional

Filters to one lifecycle state.

Allowed values:

task_familystringOptional

Filters to an exact task-family slug.

verificationenumOptional

Filters to one verification strength.

Allowed values:

Response

itemslist of objectsOptional

The Traces on this page.

next_cursorstringOptional

Opaque cursor for retrieving the next page, present only when more results are available.

total_sizeintegerOptional

The total number of Traces matching the filters within the owning Agent.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error