Abandon Agent Trace

POST

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

POST

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

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

{
  "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

highest_accepted_sequenceintegerRequired

assertion_uuidstringOptional

expected_revisionintegerOptional>=1

missing_sequence_rangeslist of objectsOptional

reasonstringOptional

verificationenumOptional

Allowed values:

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