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 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.

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:

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

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:

{
  "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`	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`	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`	RouterService
`ToolCall`	ExecutionService