Correct Agent Trace Task Family

POST

https://api.getzep.com/api/v4/agents/:agent_uuid/traces/:trace_uuid/correct-task-family

POST

/api/v4/agents/:agent_uuid/traces/:trace_uuid/correct-task-family

from zep_cloud import Zep
client = Zep(
    api_key="YOUR_API_KEY_HERE",
)
client.agent.trace.correct_task_family(
    agent_uuid="agent_uuid",
    trace_uuid="trace_uuid",
    expected_revision=1,
    reason="acknowledged_gap",
    task_family="support/refund",
)

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

expected_revisionintegerRequired>=1

The current Trace revision used for optimistic concurrency.

reasonstringRequired

Why the terminal Trace classification is being corrected.

task_familystring or nullRequired

Replacement task-family slug. Set to null to clear it.

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