Close Agent Trace

POST

https://api.getzep.com/api/v4/agents/:agent_uuid/traces/:trace_uuid/close

POST

/api/v4/agents/:agent_uuid/traces/:trace_uuid/close

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

{
  "task": {
    "completed_at": "string",
    "created_at": "string",
    "error": {
      "code": "string",
      "details": {},
      "message": "string",
      "param": "string",
      "request_id": "string"
    },
    "progress": {
      "stage": "string"
    },
    "result": {
      "content_policy": {
        "category_keys": [
          "health"
        ],
        "dropped_count": 0,
        "failed_count": 1,
        "retained_count": 7,
        "revision": 3,
        "status": "complete",
        "violated": false,
        "violated_count": 2
      },
      "edge_uuid": "7a1f3c2e-4b5d-4e6f-8a9b-0c1d2e3f4a5b",
      "edges": [
        {
          "edge_uuid": "7a1f3c2e-4b5d-4e6f-8a9b-0c1d2e3f4a5b",
          "source_node_uuid": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
          "target_node_uuid": "c3d4e5f6-a7b8-4c9d-8e1f-2a3b4c5d6e7f"
        }
      ],
      "episode_uuid": "f6a7b8c9-d0e1-4f2a-9b4c-5d6e7f8091a2",
      "episodes": [
        {
          "content_policy": {
            "category_keys": [
              "health"
            ],
            "dropped_count": 0,
            "failed_count": 1,
            "retained_count": 7,
            "revision": 3,
            "status": "complete",
            "violated": false,
            "violated_count": 2
          },
          "episode_uuid": "f6a7b8c9-d0e1-4f2a-9b4c-5d6e7f8091a2"
        }
      ],
      "hyperedge_uuid": "d4e5f6a7-b8c9-4d0e-9f2a-3b4c5d6e7f80",
      "skill_uuid": "e5f6a7b8-c9d0-4e1f-8a3b-4c5d6e7f8091",
      "source_node_uuid": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
      "target_node_uuid": "c3d4e5f6-a7b8-4c9d-8e1f-2a3b4c5d6e7f"
    },
    "started_at": "string",
    "status": "pending",
    "type": "string",
    "updated_at": "string",
    "uuid": "string"
  },
  "trace": {
    "abandoned_at": "2026-01-01T00:01:00Z",
    "agent_uuid": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
    "attempt_family_uuid": "d4e5f6a7-b8c9-4d0e-9f2a-3b4c5d6e7f80",
    "closed_at": "2026-01-01T00:01:00Z",
    "created_at": "2026-01-01T00:00:00Z",
    "internal": {
      "assertion_uuid": "6a906e70-50ca-4e43-a874-5fcae02a71fa",
      "closing_sequence": 1,
      "current_summary_version": 1,
      "last_task_uuid": "6a906e70-50ca-4e43-a874-5fcae02a71fa",
      "next_sequence": 1,
      "processing_state": "idle"
    },
    "learn_from": true,
    "learn_from_reason": "caller_opt_out",
    "metadata": {},
    "objective": "Refund a duplicate charge.",
    "outcome": "unknown",
    "parent_trace_uuid": "c3d4e5f6-a7b8-4c9d-8e1f-2a3b4c5d6e7f",
    "revision": 1,
    "source": {
      "connection_uuid": "6a906e70-50ca-4e43-a874-5fcae02a71fa",
      "import_uuid": "6a906e70-50ca-4e43-a874-5fcae02a71fa",
      "imported_at": "2026-01-01T00:00:00Z",
      "kind": "trace_import",
      "provider": "braintrust",
      "provider_project_id": "project-123",
      "run_uuid": "6a906e70-50ca-4e43-a874-5fcae02a71fa",
      "scores": {},
      "source_changed": false,
      "source_revision": "revision-1",
      "source_url": "https://example.com/traces/trace-123",
      "trace_ended_at": "2026-01-01T00:00:00Z",
      "trace_id": "provider-trace-123",
      "trace_started_at": "2026-01-01T00:00:00Z"
    },
    "status": "open",
    "task_family": "support/refund",
    "task_family_inference": {
      "assigned_at": "2026-01-01T00:00:00Z",
      "classifier_version": "task-family-classifier-v1",
      "confidence": 0.5,
      "descriptor_version": 1,
      "learning_reusable": false,
      "state": "pending"
    },
    "task_family_source": "declared",
    "trace_id": "support-001",
    "updated_at": "2026-01-01T00:00:00Z",
    "uuid": "6a906e70-50ca-4e43-a874-5fcae02a71fa",
    "verification": "none"
  }
}

Authentication

AuthorizationApi-Key

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

Path parameters

agent_uuidstringRequired

Agent UUID

trace_uuidstringRequired

Trace UUID

Request

Request body

closing_sequenceintegerOptional

expected_revisionintegerOptional>=1

missing_sequence_rangeslist of objectsOptional

outcomeenumOptional

Allowed values:

reasonstringOptional

verificationenumOptional

Allowed values:

verifierobjectOptional

verifier_idstringOptional

Response

Accepted

taskobjectOptional

The service returns the asynchronous Task.

traceobjectOptional

The service returns the finalized Trace.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error