<!-- Generated by `just docs` from proto/automaton/v1/traces.proto. Edit the source, not this file. -->

# TracesService

Read back one decision and everything that ran under it. The id is the one search returned, so code that kept it can read its own turn back later, with what was offered and what was done.

Every call is a POST to `https://api.atmon.ai/automaton.v1.TracesService/<Call>` with a JSON body, and authenticates with `Authorization: Bearer <your project key>`. Field names in JSON are lowerCamelCase, so the field written `tool_slug` below is `toolSlug` on the wire. [How to call the API](./index.md) has the whole convention.

## Calls

| Call | Request | Response | Summary |
| --- | --- | --- | --- |
| `ListTraces` | `ListTracesRequest` | `ListTracesResponse` | Lists traces newest first, optionally narrowed to one entity, one toolkit's tools, or a time window. |
| `GetTrace` | `GetTraceRequest` | `GetTraceResponse` | Reads one decision and the ledger rows that ran under it. |

### ListTraces

Lists traces newest first, optionally narrowed to one entity, one toolkit's
tools, or a time window.

Request `ListTracesRequest`, response `ListTracesResponse`.

```http
POST /automaton.v1.TracesService/ListTraces HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{
  "entityId": "...",
  "toolkitSlug": "...",
  "from": "2026-01-31T09:15:00Z",
  "to": "2026-01-31T09:15:00Z",
  "pageSize": 0,
  "pageToken": "..."
}
```

The response:

```json
{
  "traces": [{
    "id": "...",
    "entityId": "...",
    "intent": "...",
    "matchedToolSlugs": ["..."],
    "createdAt": "2026-01-31T09:15:00Z",
    "reportedOutcome": "OUTCOME_SUCCESS",
    "reportedDetail": "...",
    "reportedAt": "2026-01-31T09:15:00Z",
    "callCount": 0
  }],
  "nextPageToken": "..."
}
```

### GetTrace

Reads one decision and the ledger rows that ran under it. This is the view
that separates "the router offered the wrong tool" from "the agent called
the right tool badly".

Request `GetTraceRequest`, response `GetTraceResponse`.

```http
POST /automaton.v1.TracesService/GetTrace HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{
  "id": "..."
}
```

The response:

```json
{
  "trace": {
    "id": "...",
    "entityId": "...",
    "intent": "...",
    "matchedToolSlugs": ["..."],
    "createdAt": "2026-01-31T09:15:00Z",
    "reportedOutcome": "OUTCOME_SUCCESS",
    "reportedDetail": "...",
    "reportedAt": "2026-01-31T09:15:00Z",
    "callCount": 0
  },
  "toolCalls": [{
    "id": "...",
    "entityId": "...",
    "toolSlug": "...",
    "connectedAccountId": "...",
    "argumentsJson": "{}",
    "status": "TOOL_CALL_STATUS_RUNNING",
    "resultJson": "{}",
    "errorCode": "...",
    "errorDetail": "...",
    "startedAt": "2026-01-31T09:15:00Z",
    "finishedAt": "2026-01-31T09:15:00Z",
    "approvalId": "...",
    "resultTruncated": true,
    "resourceUrn": "...",
    "leaseWaitMs": 0,
    "principalChain": ["..."],
    "jobId": "...",
    "stepId": "...",
    "relayId": "..."
  }]
}
```

## Messages

### GetTraceRequest

| Field | Type | # | Notes |
| --- | --- | --- | --- |
| `id` | `string` | 1 |  |

### GetTraceResponse

| Field | Type | # | Notes |
| --- | --- | --- | --- |
| `trace` | `Trace` | 1 |  |
| `tool_calls` | repeated [`ToolCall`](./execution.md#toolcall) | 2 | linked ledger rows, oldest first |

### ListTracesRequest

| Field | Type | # | Notes |
| --- | --- | --- | --- |
| `entity_id` | `string` | 1 | empty lists every entity in the project |
| `toolkit_slug` | `string` | 2 | keep traces that matched a tool of this toolkit |
| `from` | `google.protobuf.Timestamp` | 3 | inclusive lower bound on created_at |
| `to` | `google.protobuf.Timestamp` | 4 | exclusive upper bound on created_at |
| `page_size` | `int32` | 5 |  |
| `page_token` | `string` | 6 |  |

### ListTracesResponse

| Field | Type | # | Notes |
| --- | --- | --- | --- |
| `traces` | repeated `Trace` | 1 | newest first |
| `next_page_token` | `string` | 2 |  |

### Trace

| Field | Type | # | Notes |
| --- | --- | --- | --- |
| `id` | `string` | 1 | the resolution id from ResolveTools |
| `entity_id` | `string` | 2 |  |
| `intent` | `string` | 3 |  |
| `matched_tool_slugs` | repeated `string` | 4 | ranked best first |
| `created_at` | `google.protobuf.Timestamp` | 5 |  |
| `reported_outcome` | [`Outcome`](./router.md#outcome) | 6 | OUTCOME_UNSPECIFIED until the agent reports |
| `reported_detail` | `string` | 7 |  |
| `reported_at` | `google.protobuf.Timestamp` | 8 | absent until the agent reports |
| `call_count` | `int32` | 9 | ledger rows linked to this trace |

## Types from other calls

These are described on another page of this reference, so there is one description of each.

| Type | Described under |
| --- | --- |
| [`Outcome`](./router.md#outcome) | RouterService |
| [`ToolCall`](./execution.md#toolcall) | ExecutionService |