Get Chat Session

Retrieve a chat session by its ID. Optionally include the full message history, per-response status events, and user votes on messages.

Callers typically poll this endpoint after sending a prompt to watch for status to return to active and pick up the generated response.

GET /chat-v1/sessions/{session_id}

Path Parameters

Query Parameters

NOTE

• Returns 404 if the session does not exist or does not belong to the user.
• While the response is still being generated, the session status will be finding_sources or generating_response and the response message may be absent from messages. Poll until status is active.

Request

https://premium.aiera.com/api/chat-v1/sessions/2229?include_messages=true

Response (status: finding_sources)

{
  "id": 2229,
  "title": "API Docs Example",
  "title_status": "user",
  "status": "finding_sources",
  "active_message_id": null,
  "messages": [
    {
      "id": 20712,
      "session_id": 2229,
      "message_type": "prompt",
      "content": "What were the key takeaways from Tesla Q1 2026 earnings?",
      "ordinal_id": null,
      "prompt_message_id": null,
      "runner_version": null,
      "tool_settings": null,
      "user_id": 9846,
      "sources": null,
      "created_at": "2026-04-29T20:52:26Z",
      "updated_at": "2026-04-29T20:52:26Z"
    }
  ],
  "sources": null,
  "model_generation_params": null,
  "model_id": null,
  "user_id": 9846,
  "votes": null,
  "created_at": "2026-04-29T20:52:25Z",
  "updated_at": "2026-04-29T20:52:25Z"
}

Response (status: active, response ready)

When status is active, the response message appears in messages. Response messages carry blocks with rendered content and inline citations, plus a sources array enumerating every document referenced.

{
  "id": 2227,
  "title": "NVIDIA Price Targets Research",
  "title_status": "user",
  "status": "active",
  "active_message_id": null,
  "messages": [
    {
      "id": 20695,
      "session_id": 2227,
      "message_type": "prompt",
      "content": "What is the current consensus on NVIDIA stock price targets?",
      "user_id": 9846,
      "created_at": "2026-04-29T20:47:55Z",
      "updated_at": "2026-04-29T20:47:55Z"
    },
    {
      "id": 20702,
      "session_id": 2227,
      "message_type": "response",
      "prompt_message_id": 20695,
      "runner_version": "3",
      "user_id": 9846,
      "blocks": [
        {
          "type": "text",
          "content": "## NVIDIA (NVDA) — Current Consensus on Stock Price Targets\n\n### Research Insights\n\nThe analyst community remains broadly constructive on NVIDIA...",
          "citations": [
            {
              "marker": "research_evercore_0b2b3a2a-b3e7-4bd2-bc05-3d8b3359d586",
              "author": "Evercore ISI",
              "date": "2025-11-20",
              "quote": "**Evercore ISI Focus** **NVIDIA Corp. (NVDA)** NVDA - Outperform; Price Target $352.0 ...",
              "url": "https://app.aiera.com/research/evercore_0b2b3a2a-b3e7-4bd2-bc05-3d8b3359d586?page=4",
              "source": {
                "id": "evercore_0b2b3a2a-b3e7-4bd2-bc05-3d8b3359d586",
                "name": "FirstLook",
                "type": "research",
                "meta": {
                  "page": 4,
                  "provider": "evercore",
                  "relevant_date": "2025-11-20",
                  "url": null
                },
                "parent": {
                  "id": "evercore_0b2b3a2a-b3e7-4bd2-bc05-3d8b3359d586",
                  "name": "FirstLook",
                  "type": "research",
                  "meta": null,
                  "parent": null
                }
              }
            }
          ]
        }
      ],
      "sources": [
        {
          "id": "evercore_0b2b3a2a-b3e7-4bd2-bc05-3d8b3359d586",
          "name": "FirstLook",
          "type": "research",
          "meta": {
            "provider": "evercore",
            "relevant_date": "2025-11-20",
            "url": null
          },
          "parent": null
        }
      ],
      "created_at": "2026-04-29T20:49:06Z",
      "updated_at": "2026-04-29T20:49:06Z"
    }
  ],
  "user_id": 9846,
  "created_at": "2026-04-29T20:47:54Z",
  "updated_at": "2026-04-29T20:51:52Z"
}

Response (404)

{
  "error": "Chat session 999999 for user 9846 not found"
}

Code Samples

Bash

curl --request GET \
  --url 'https://premium.aiera.com/api/chat-v1/sessions/2229?include_messages=true' \
  --header 'X-API-Key: your-rest-api-key'

Python

import requests
requests.get(
    "https://premium.aiera.com/api/chat-v1/sessions/2229",
    params={"include_messages": "true"},
    headers={"X-API-Key": "your-rest-api-key"},
)