Sessions
A session is one conversation. Each question starts a turn. A session runs one turn at a
time, and its status describes the latest turn, not the whole conversation.
Paths on this page are relative to
https://api.research.alpha-sense.com/superanalyst/v1/superanalysts/default. The samples continue
from the Quick Start and reuse api, API_URL, and the session
URL.
Statuses
status | Meaning | Can you ask a follow-up? |
|---|---|---|
queued | The turn is accepted and about to start | No, returns 409 |
in_progress | The turn is running | No, returns 409 |
completed | The turn finished with an answer | Yes |
failed | The turn ended without an answer | Yes |
cancelled | The turn was stopped by you or SuperAnalyst | Yes |
timed_out | The turn ran out of time | Yes |
completed means the turn is done. The conversation stays open for more questions.
A failed or timed-out turn is not an HTTP error. The session returns 200 with an error object
that has code, message, and retryable. To retry, ask the question again as a follow-up.
The session object
{
"id": "…",
"object": "session",
"title": "NVIDIA earnings call themes",
"superanalyst_id": "default",
"model": null,
"status": "completed",
"cancelled_at": null,
"error": null,
"metadata": {}
}
idis opaque and can contain:. URL-encode it once when you put it in a path.titleisnulluntil SuperAnalyst names the conversation.modelandmetadataecho what you sent, on the create or follow-up response only.cancelled_atis set only on a cancel response that stopped a running turn.- Sessions have no timestamps. Use the
created_atof their messages.
Start a session
POST /sessions creates a session and starts its first turn.
{
"input": {"text": "Compare AMD and NVIDIA data center revenue growth."},
"metadata": {"ticket": "RES-1042"}
}
input.textis required and must not be blank.input.type, if sent, must betext.modelis optional. Omit it, or senddefault.metadatais optional: your own string key/value pairs, echoed back and never shown to SuperAnalyst.- Unknown fields return
400 INVALID_REQUESTnaming the field.optionsreturns400 UNSUPPORTED_OPERATION.
The response is the session with status: "queued". Send Accept: text/event-stream instead to
stream the first turn.
Requests are not idempotent. Sending the same request twice starts two turns, and both use credits. If a request times out, check the session before you send it again.
Ask a follow-up
POST /sessions/{session_id}/messages starts the next turn. It takes the same body. Omitting
model keeps the session's current model; default resets it.
The response is the session with status: "queued".
- Right after you send a follow-up, the session can still show the previous turn's status. To wait
for the new answer, check for a newer assistant message, as
wait_for_answerdoes in the Quick Start. - Send one follow-up at a time, and wait for its answer before the next.
Check a session
GET /sessions/{session_id} returns the session object. It is cheap, so you can poll it every few
seconds until the status is no longer queued or in_progress.
Cancel a turn
POST /sessions/{session_id}/cancel stops the running turn. It takes no body and is safe to call
twice.
curl -sS -X POST "$SESSION_URL/cancel" -H "Authorization: Bearer $ACCESS_TOKEN"
- The session is kept. Wait until its status is no longer
queuedorin_progressbefore you ask a follow-up; the stop takes a moment. - A cancel sent in the first few seconds of a turn may not take effect. Check the session after a
few seconds, and call cancel again if it is still
queuedorin_progress. - Closing a stream does not cancel a turn. Only this endpoint stops it.
List sessions
GET /sessions lists your sessions, most recently active first, including ones started in the
AlphaSense web app. Pass the next_cursor of one page as cursor to get the next. Stop when
next_cursor is null; a short page is not the end. limit ranges are in
Pagination.
- Python
- JavaScript
- cURL
def list_sessions():
params = {"limit": 100}
while True:
page = api.get(f"{API_URL}/sessions", params=params).json()
yield from page["data"]
if not page["next_cursor"]:
return
params["cursor"] = page["next_cursor"]
for session in list_sessions():
print(session["status"], session["title"])
async function* listSessions() {
let cursor = null
do {
const query = new URLSearchParams({limit: 100, ...(cursor && {cursor})})
const page = await api(`/sessions?${query}`)
yield* page.data
cursor = page.next_cursor
} while (cursor)
}
for await (const session of listSessions()) console.log(session.status, session.title)
curl -sS "$API_URL/sessions?limit=100" -H "Authorization: Bearer $ACCESS_TOKEN" \
| jq '{next_cursor, sessions: [.data[] | {title, status}]}'
Read the transcript
GET /sessions/{session_id}/messages returns the conversation, oldest first:
{
"object": "list",
"session_id": "…",
"session_status": "completed",
"data": [
{
"id": "…",
"role": "assistant",
"content": [{"type": "text", "text": "NVIDIA's call centered on three themes…"}],
"citations": [
{
"type": "document",
"id": "…",
"title": "Nvidia's data center sales jump",
"source": "Financial Times",
"url": "https://research.alpha-sense.com/…",
"document_id": "…",
"page": 3,
"statement_ids": ["…"],
"broker_code": null,
"broker_name": null,
"text_ranges": [{"start": 38, "end": 38}]
}
],
"artifacts": [{"name": "nvidia_themes.md", "file_id": null}],
"created_at": "2026-11-16T14:04:37Z"
}
],
"next_cursor": null,
"dropped_older_messages": 0
}
roleisuserfor your questions andassistantfor answers.contentholds one text part. The text is Markdown, with no source links.citationslists the answer's sources and where the text cites them. See Citations.artifactsnames the files an answer produced. To download them, use the artifacts endpoints.session_statusofqueuedorin_progressmeans the latest answer is not saved yet.
limit keeps only the newest messages, still oldest first. dropped_older_messages counts the ones
left out. There is no paging.
To read only the latest answer, request limit=1 after the turn completed. If the turn failed or
was cancelled, the newest message is your question, and there is no answer to read.
Use the transcript as the record of the conversation. Streamed events are not replayed, so the transcript is how you recover an answer you missed.