How often should I poll?

The ask response includes a suggested interval in milliseconds. Using it avoids both hammering the endpoint and waiting far longer than necessary.

What can include take?

Only events. Repeating the parameter or comma-separating it is supported, but there is no second value to combine it with today.

Does polling cost credits?

No. Reading a session is free, however many times you do it. Only the work that created the session was billed.

Where do session ids come from?

From the ask endpoint, from triggering an automation run, and from inbox rows, which name the session a row came out of.

Why is the trace the thing to read when an answer is wrong?

Because it shows which tools ran with which arguments. A wrong answer is usually a right answer about the wrong window, topic or URL, and the trace makes that visible immediately.

REST API endpoint

GET /v1/sessions/{id} — poll async work and read the agent's trace

Fetches a session started by an ask or an automation run — its status, its answer once finished, and optionally the step-by-step trace of what the agent did.

Karl-Gustav Kallasmaa, Founder & CEOLast updated 4 September 2026

GET /v1/sessions/{id}Needs read scopeSpends no creditsMCP tool: get_session

The request

Paste this and change the key. Every endpoint takes a bearer key and none takes a workspace id — the key names the workspace.

curl "https://api.attensira.com/v1/sessions/ses_9d02?include=events" \
  -H "Authorization: Bearer atn_live_<your key>"

Parameters

Every parameter the published reference documents, and nothing it does not.

Name	In	Type	Default	Notes
id*	path	string	—	A session id from an ask, from an automation run, or from an inbox row.
include	query	string	—	events returns the step-by-step trace. It is the only supported value — repeat the parameter or comma-separate it.

The response (200)

Abbreviated, never invented — this is the shape the published reference documents.

{
  "id": "ses_9d02",
  "status": "complete",
  "answer": "Your pricing page is cited on Perplexity but not on ChatGPT, because…",
  "events": [
    { "type": "fetch", "at": "2026-09-02T08:00:04Z", "detail": "read acme.com/pricing" }
  ]
}

What goes wrong, and what it means

The condition on the left, the correct reading of it on the right.

The answer is null and the status is running: The work is not finished. Keep polling; the ask response's suggested interval is the right cadence to use.
The status is failed: The run ended without an answer. The event trace is the only record of how far it got, and it is worth reading before spending credits on a retry.
The answer looks wrong: Ask for events. The trace names which tools were called and with what arguments, which usually reveals that the agent read a different slice than you assumed.

What this endpoint cannot tell you

The limits are part of the answer, not a disclaimer under it.

It cannot tell you what the run cost. The session carries status, answer and trace; billing is reported by the endpoint that started the work and by the account's credit balance.
The trace records what the agent did, not why it decided to. It is a log of calls and arguments rather than an explanation of the reasoning behind them.

Two endpoints in this API hand back work in progress rather than a result: asking the agent, and triggering an automation run. Both return a session id, and this is the endpoint that turns that id into something.

The polling half

Fetch the session and read the status. running means keep waiting. complete means the answer field is populated. failed means the run ended without producing one.

Polling is free — reading a session spends nothing, no matter how often you do it — so the only cost of a tight loop is your own request budget. The ask endpoint returns a suggested interval, and using it is the sensible middle between hammering and sleeping far longer than the work takes.

An integration built on either async endpoint has to be asynchronous the whole way through. Code that treats a running status as an error, or that reads the answer field once and gives up when it is null, will work in testing against a fast question and fail against a slow one.

The trace half, which is the interesting one

Pass include=events and the response carries a step-by-step record of what the agent actually did: the tools it called, the arguments it called them with, and when. It is the only supported value of that parameter today.

That trace is the most underused thing in the API. When an agent answer looks wrong, the cause is almost never that the agent invented something — it is that it read a different slice than you assumed. A thirty-day window where you meant ninety. A topic filter that matched more loosely than expected. A page URL in a form you do not publish. All of those produce a fluent, confident, wrong answer, and all of them are immediately visible in a list of calls and arguments.

Reading the trace before re-asking also saves credits. Asking again gets you a second answer to the same misunderstood question; reading the trace tells you which part of the question to change.

Where session ids come from

Three places. The ask endpoint returns one for every investigation. Triggering an automation run returns one for that run, and the single-automation endpoint inlines the most recent one. And inbox rows name the session they came out of, which is how you get from "the agent is blocked on something" to the full context of what it was attempting.

What the session does not carry

It does not report cost. Credits are reported by the endpoints that spend them and by the account's balance, not by the record of the work.

And the trace is a log rather than an explanation. It faithfully says which tools ran with which arguments; it does not narrate why the agent chose them. That is the right scope for a machine-readable record, and it is worth knowing so that nobody goes looking in the events for reasoning that was never claimed to be there.

Its twin on the other surface

The get_session MCP tool takes the same id and an include array, where passing ["events"] produces the same trace. Since it is read-only and free, it is a reasonable tool to leave enabled anywhere the ask tool is enabled — an assistant that can start work and cannot check on it is not much use.

A note on retention of your own records

Because only the most recent run is inlined elsewhere and this endpoint addresses one session at a time, the history of what an agent has produced over months is something you assemble rather than something you query. If that history matters — for an audit, for a report on whether automated work is paying for itself — record the session id and the final status each time you poll, and keep the series on your side. It is a handful of fields and it turns a set of point lookups into something you can actually reason about later.

Questions people ask

How often should I poll?: The ask response includes a suggested interval in milliseconds. Using it avoids both hammering the endpoint and waiting far longer than necessary.
What can include take?: Only events. Repeating the parameter or comma-separating it is supported, but there is no second value to combine it with today.
Does polling cost credits?: No. Reading a session is free, however many times you do it. Only the work that created the session was billed.
Where do session ids come from?: From the ask endpoint, from triggering an automation run, and from inbox rows, which name the session a row came out of.
Why is the trace the thing to read when an answer is wrong?: Because it shows which tools ran with which arguments. A wrong answer is usually a right answer about the wrong window, topic or URL, and the trace makes that visible immediately.

Sources

Every factual statement above, with the page it came from and the date that page was read.

The Attensira API reference states that the events trace shows which tools the agent called and with what arguments, and is the place to look when an answer seems wrong.
docs.attensira.com · retrieved 2026-09-04
“The events trace shows which tools the agent called and with what arguments — the place to look when an answer seems wrong and you want to know which slice it read.”
The API reference states that events is the only supported value of the include parameter on the sessions endpoint.
docs.attensira.com · retrieved 2026-09-04
“Optional. events returns the step-by-step trace. The only supported value”

The reference this is written from →Every endpoint →The same capability over MCP →