Skip to main content

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​

statusMeaningCan you ask a follow-up?
queuedThe turn is accepted and about to startNo, returns 409
in_progressThe turn is runningNo, returns 409
completedThe turn finished with an answerYes
failedThe turn ended without an answerYes
cancelledThe turn was stopped by you or SuperAnalystYes
timed_outThe turn ran out of timeYes

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": {}
}
  • id is opaque and can contain :. URL-encode it once when you put it in a path.
  • title is null until SuperAnalyst names the conversation.
  • model and metadata echo what you sent, on the create or follow-up response only.
  • cancelled_at is set only on a cancel response that stopped a running turn.
  • Sessions have no timestamps. Use the created_at of 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.text is required and must not be blank. input.type, if sent, must be text.
  • model is optional. Omit it, or send default.
  • metadata is optional: your own string key/value pairs, echoed back and never shown to SuperAnalyst.
  • Unknown fields return 400 INVALID_REQUEST naming the field. options returns 400 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_answer does 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 queued or in_progress before 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 queued or in_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.

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"])

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
}
  • role is user for your questions and assistant for answers.
  • content holds one text part. The text is Markdown, with no source links.
  • citations lists the answer's sources and where the text cites them. See Citations.
  • artifacts names the files an answer produced. To download them, use the artifacts endpoints.
  • session_status of queued or in_progress means 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.