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

# Outcomes

> Reporting what happened after the agent proposed an action for you to carry out.

Some work Patchwork cannot do. A step that must happen in your UI, on a device, or by a human is declared as a `proposed_action` patch. The agent proposes it, the run pauses in `awaiting_outcome`, and waits for you to say what happened.

This is the mirror image of a [confirmation](/guides/confirmations): there we ask permission before acting, here you act and then report.

## Finding a pending action

`GET /v1/loom/threads` returns `pending_action` on the thread:

```json theme={null}
{
  "pending_action": {
    "run_id": "7c9e6679-…",
    "tool_call_id": "9b1deb4d-…",
    "patch_ref": "collect_signature@2",
    "args": { "document_id": "doc_881" }
  }
}
```

`args` is what the agent proposed. Carry it out however your product does.

## Reporting

```bash theme={null}
curl -X POST https://api.usepatchwork.co/v1/loom/runs/<run_id>/outcome \
  -H "Authorization: Bearer sk_live_..." \
  -H "Patchwork-Subject: user_9f2" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_call_id": "9b1deb4d-…",
    "state": "occurred",
    "detail": { "signed_at": "2026-08-30T12:04:00Z" }
  }'
```

| `state` | Meaning |
| - | - |
| `occurred` | The action happened. |
| `failed` | It did not. The model is told, and can respond. |

`detail` is optional, recorded on the outcome, and passed to the model. A short structured reason produces a better next turn than a bare `failed`.

The response is `202` and the run resumes.

## Idempotent

Posting an outcome for a tool call that already has one returns success without doing anything. Safe to retry.

## Errors

| Code | Status | When |
| - | - | - |
| `unknown_action` | `404` | No proposed action with that `tool_call_id` on that run. |
| `not_awaiting_outcome` | `422` | The run is not waiting for one. |
| `invalid_state` | `422` | `state` was not `occurred` or `failed`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.