When should I use this instead of the measurement endpoints?

When the question is why rather than what. Any metric or ranked list is free and immediate from the analytics endpoint, and this costs credits and takes time because it does work.

Why is the answer null?

Because the run has not finished. A running status with a null answer is the normal first response, and poll_after_ms tells you how long to wait before polling the session.

What does the agent actually do?

It crawls pages, audits them as a model sees them, and searches the web, alongside reading your tracking data. The session's event trace records which of those it did.

Can I continue a previous investigation?

Yes. Pass the session id from an earlier ask and the new question continues that thread instead of starting a fresh one.

REST API endpoint

POST /v1/ask — the agent investigates what a metric cannot explain

Open-ended investigation run by the Attensira agent, which crawls pages, audits them as a model sees them and searches the web. Spends credits and returns a handle.

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

POST /v1/askNeeds write scopeSpends creditsMCP tool: ask

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 -X POST https://api.attensira.com/v1/ask \
  -H "Authorization: Bearer atn_live_<your key>" \
  -H "Content-Type: application/json" \
  -d '{"question":"why is our pricing page cited on Perplexity but not on ChatGPT?"}'

Parameters

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

Name	In	Type	Default	Notes
question*	body	string	—	In plain language. The agent decides which slices to read.
session	body	string	—	A session id from a previous ask, to continue that thread rather than starting a new one.

The response (200)

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

{
  "session_id": "ses_9d02",
  "status": "running",
  "answer": null,
  "poll_after_ms": 4000
}

What goes wrong, and what it means

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

status comes back running with a null answer: That is the success case, not an error. Wait poll_after_ms and then poll the sessions endpoint until the answer is present.
status comes back failed: The run ended without producing an answer. The session's event trace shows how far it got, which is usually more informative than re-asking the same question.
The answer restates a number you could have fetched: The question was a measurement question. Those are answered free and instantly by the analytics, prompt and page endpoints, and sending them here spends credits for a slower version.

What this endpoint cannot tell you

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

It cannot give you a visibility score or a sentiment reading, because Attensira has neither. What it can do is investigate why the rates you do have look the way they do.
It cannot answer instantly. The response is a handle with a suggested polling interval, so any integration built on it has to be asynchronous — treating a running status as a failure is the classic mistake.

Every other read endpoint in this API answers a question of the form "what". This one answers "why", and it is the only one that does actual work to get there.

What separates it from a metric call

The measurement endpoints report what was observed. They are fast, they are free, and they are complete for any question that is really a lookup: a rate, a ranked list, the sources cited against a prompt, the prompts that cited a page.

The agent is for the questions those cannot reach. It crawls pages, audits them the way a model sees them, and searches the web, in addition to reading your tracking data. That is why it costs credits and why it takes time — it is not a slower query against the same table, it is a different kind of operation.

The documented advice is to try a measurement endpoint first, and it is worth taking literally. A question phrased as "what is our mention rate on Perplexity" has a free, instant, exact answer elsewhere. Sending it here buys a slower version of the same number with a charge attached.

The response is asynchronous, and running is success

You will usually get back a session id, a running status, a null answer, and a suggested wait in milliseconds. Nothing has gone wrong. The API is telling you that work has started and roughly when to look again.

This trips up more integrations than any other behaviour in the API, because a null field and a non-terminal status look like a failure to code that expects request and response to be the same thing. They are not. Poll the sessions endpoint with the id after the suggested interval, and keep polling until the status is complete or failed.

A failed status means the run ended without an answer. Before re-asking, fetch the session with its event trace: it shows how far the agent got and what it was doing when it stopped, which is generally more useful than paying to run the same question again.

Continuing a thread

The optional session argument continues an earlier investigation instead of starting a new one. That is more than a convenience — an investigation that already knows which pages it read and what it concluded does not need to rediscover them, and a follow-up question against the same thread is a genuinely different thing from the same question asked cold.

Two words that mean different things

The agent runs on an agent model, which is the LLM doing the investigating. A tracked platform is an answer surface Attensira reads on your behalf to collect measurements. They are unrelated systems, and changing which model the agent uses does not change a single measured number.

This is worth internalising because the two are easy to conflate in a sentence, and conflating them produces the belief that switching agent models will move your visibility. It will not: it changes who is doing the reasoning about your data, not what data was collected.

Cost discipline

Three endpoints in this API spend credits, and this is the open-ended one. A good habit is to make the cheap calls first and hand the agent a narrower question as a result: not "why are we losing", but "our mention rate for these four prompts fell and their answers cite these three domains — what on our pricing page is missing". A well-scoped question costs less and produces something you can act on.

Its twin on the other surface

The ask MCP tool takes the same question and optional session, needs the write scope, and spends credits identically. It carries the same instruction to reach for the read tools first, for exactly the same reason.

Questions people ask

When should I use this instead of the measurement endpoints?: When the question is why rather than what. Any metric or ranked list is free and immediate from the analytics endpoint, and this costs credits and takes time because it does work.
Why is the answer null?: Because the run has not finished. A running status with a null answer is the normal first response, and poll_after_ms tells you how long to wait before polling the session.
What does the agent actually do?: It crawls pages, audits them as a model sees them, and searches the web, alongside reading your tracking data. The session's event trace records which of those it did.
Can I continue a previous investigation?: Yes. Pass the session id from an earlier ask and the new question continues that thread instead of starting a fresh one.
Is the agent model the same as a tracked platform?: No. The agent model is the LLM powering the investigation; a tracked platform is an answer surface Attensira reads on your behalf. Changing one does not change the other.

Sources

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

The Attensira API reference states that a running response from the ask endpoint is the success case rather than an error.
docs.attensira.com · retrieved 2026-09-04
“A running response is the success case, not an error.”
The API reference states that the measurement endpoints should be tried first because they are free and immediate, while the agent costs credits and takes time.
docs.attensira.com · retrieved 2026-09-04
“Those are free and immediate; this costs credits and takes time.”
The API reference distinguishes the agent model — the LLM powering the chat — from a tracked platform, the answer surface Attensira reads, and states that changing the agent model does not change what is measured.
docs.attensira.com · retrieved 2026-09-04
“Changing your agent model does not change what is measured.”

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