Get a consultation

Returns the consultation with its full message history. Poll this endpoint to receive Kaal's answers. Free.

GET/v1/consultations/:id

Path parameters

idstringrequired

The consultation ID returned by Create a consultation.

Request

curl {BASE}/v1/consultations/6e241e38-dd8f-428b-ae09-a8d7169335d3 \
  -H "Authorization: Bearer $KAALERA_API_KEY"

const res = await fetch("{BASE}/v1/consultations/6e241e38-dd8f-428b-ae09-a8d7169335d3", {
  headers: { Authorization: `Bearer ${process.env.KAALERA_API_KEY}` },
});
const data = await res.json();
console.log(res.status, data);

import os, requests

res = requests.get(
    "{BASE}/v1/consultations/6e241e38-dd8f-428b-ae09-a8d7169335d3",
    headers={"Authorization": f"Bearer {os.environ['KAALERA_API_KEY']}"},
)
print(res.status_code, res.json())

Response

{
  "consultation": {
    "id": "6e241e38-dd8f-428b-ae09-a8d7169335d3",
    "name": "Asha Verma",
    "language": "English",
    "status": "ready",
    "created_at": "2026-10-12T02:21:34.792Z",
    "expires_at": "2026-10-19T02:21:35.278Z",
    "messages": [
      {
        "id": "619016d2-4cf9-432b-848b-dcd9921a3b00",
        "role": "user",
        "content": "When is a good window for a career change?",
        "created_at": "2026-10-12T02:21:34.792Z"
      },
      {
        "id": "e72af372-ed54-4b5e-919c-a31f24f87f06",
        "role": "kaal",
        "content": "**Namaste Asha ji, I am Kaal, Kaalera's astrologer.** I have studied your Kundli, and here is a short overview before I answer your question.\n\n**Who you are**\n- **Lagna (Ascendant): Capricorn, Moon in Capricorn, Shravana nakshatra.** …",
        "created_at": "2026-10-12T02:22:52.000Z"
      }
    ]
  }
}

The kaal message above is shortened; real answers are a few thousand characters of Markdown.

consultation.statusstring

See status values.

consultation.messagesarray

All messages, oldest first.

messages[].idstring

Message ID. For your questions it equals the question_id returned when you asked.

messages[].rolestring

user (your question) or kaal (an answer).

messages[].contentstring

Message text. Kaal’s answers are Markdown.

messages[].created_atstring

ISO 8601 timestamp.

The other fields (id, name, language, created_at, expires_at) are the same as in Create a consultation.

Status values

Status	Meaning
`starting`	Kaal is being set up for this consultation.
`answering`	At least one question is waiting for an answer.
`ready`	All questions are answered. You can ask a follow-up.
`closed`	The consultation is more than 7 days old. Read-only; create a new one to ask more.
`failed`	The consultation could not continue. Unanswered questions are not charged.

Polling

Answers usually take a few minutes. Poll every 10 seconds and stop when status is ready, closed or failed.

const headers = { Authorization: `Bearer ${process.env.KAALERA_API_KEY}` };
const id = "6e241e38-dd8f-428b-ae09-a8d7169335d3";

async function waitForAnswer() {
  while (true) {
    const res = await fetch(`{BASE}/v1/consultations/${id}`, { headers });
    const { consultation } = await res.json();
    if (consultation.status === "failed" || consultation.status === "closed") throw new Error(consultation.status);
    if (consultation.status === "ready") {
      const last = consultation.messages.at(-1);
      if (last?.role === "kaal") return last.content;
    }
    await new Promise((r) => setTimeout(r, 10_000)); // poll every 10 s
  }
}

console.log(await waitForAnswer());

import os, time, requests

headers = {"Authorization": f"Bearer {os.environ['KAALERA_API_KEY']}"}
cid = "6e241e38-dd8f-428b-ae09-a8d7169335d3"

while True:
    c = requests.get(f"{BASE}/v1/consultations/{cid}", headers=headers).json()["consultation"]
    if c["status"] in ("failed", "closed"):
        raise RuntimeError(c["status"])
    if c["status"] == "ready" and c["messages"][-1]["role"] == "kaal":
        print(c["messages"][-1]["content"])
        break
    time.sleep(10)  # poll every 10 s

Errors

Status	Code	When
401	`invalid_api_key`	Missing, wrong or revoked API key.
404	`not_found`	No consultation with this ID on your account.

{
  "error": {
    "code": "not_found",
    "message": "Consultation not found."
  }
}