> ## Documentation Index
> Fetch the complete documentation index at: https://tryagentai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Escalations

> Create, read, and decide on escalations from the SDK.

# Escalations

The `escalations` resource covers the full lifecycle. Creating escalations uses a
workspace `apiKey`; the read and reviewer methods act on behalf of a user, so use
a client built with `token` or `getToken` (see [Client](/sdk/client)).

## escalate

Convenience wrapper that creates an escalation under a policy. The policy key is
the first argument; everything else is the decision content.

```typescript theme={null}
const escalation = await tryagent.escalate("orders.auth_doc", {
  agentId: "order-agent",
  runId: "run_4821",
  subject: { type: "order", id: "ord_4821", label: "Order #4821" },
  question: "The authorization document is missing a signature date. Continue?",
  evidence: [
    "Candidate name is present.",
    "Employer is present.",
    "Signature date is blank.",
  ],
  choices: [
    { id: "manual_review", label: "Send to manual review" },
    { id: "continue", label: "Continue anyway" },
  ],
  resume: {
    mode: "webhook",
    url: "https://api.example.com/tryagent/resume",
    secret: process.env.TRYAGENT_WEBHOOK_SECRET!,
  },
});

console.log(escalation.id, escalation.status); // esc_..., "open"
```

`escalate` returns as soon as TryAgent creates the escalation — it does not wait
for a reviewer. Required fields are `agentId`, `runId`, `subject`, `question`,
`evidence`, and `choices`. Optional fields include `responseFields`, `severity`,
`resume`, and `metadata`.

## escalations.create

The same call as `escalate`, with `policy` included in the input object. Use it
when you already have a fully assembled `CreateEscalationInput`.

```typescript theme={null}
const escalation = await tryagent.escalations.create({
  policy: "orders.auth_doc",
  agentId: "order-agent",
  runId: "run_4821",
  // ...the remaining decision content
});
```

## escalations.list

Returns escalations for the workspace, optionally filtered by status. Resolves to
an `Escalation[]` (the SDK unwraps the API envelope).

```typescript theme={null}
const open = await tryagent.escalations.list({ status: "open" });
```

`status` accepts `open`, `acknowledged`, `decided`, `resolved`, `breached`, or
`canceled`. Omit it to list all.

## escalations.get

Fetch a single escalation by id, including its current `status`, `decision`, and
learned `recommendation` when present.

```typescript theme={null}
const escalation = await tryagent.escalations.get("esc_123");
```

## escalations.acknowledge

Mark an open escalation as being worked on. Only `open` escalations can be
acknowledged.

```typescript theme={null}
await tryagent.escalations.acknowledge("esc_123");
```

## escalations.decide

Record a reviewer decision and resolve the escalation. `choice` must match one of
the escalation's choice ids. Include `response` when the escalation defined
`responseFields`.

```typescript theme={null}
await tryagent.escalations.decide("esc_123", {
  choice: "continue",
  reason: "Signature verified out of band.",
  response: { approvedLimit: 5000, riskLevel: "low" },
});
```

Deciding triggers the signed resume callback to your `resume.url`. Verify it with
[`webhooks.constructEvent`](/sdk/webhooks).

## escalations.cancel

Cancel an escalation without recording a choice — for example, when the
underlying run is abandoned.

```typescript theme={null}
await tryagent.escalations.cancel("esc_123", { reason: "Order withdrawn." });
```

Both `decide` and `cancel` reject escalations already in a terminal state
(`decided`, `resolved`, `breached`, `canceled`).