> ## Documentation Index > Fetch the complete documentation index at: https://docs.rhizomeai.com/llms.txt > Use this file to discover all available pages before exploring further. # Conversations > Ask Rhizome's research agent questions and get cited answers, files and follow-ups A conversation is the same thing as a conversation on [rhizomeai.com](https://rhizomeai.com): you send a question, Rhizome's research agent searches the regulatory corpus, and you get back a cited answer, plus any reports or files it wrote. You can then ask follow-ups in the same conversation. Conversations started through the API appear in your account on rhizomeai.com, and conversations started there can be continued through the API. A research run takes 1 to 10 minutes, so the API is asynchronous: 1. [Start a conversation](/api-reference/v3/conversations/create). The call returns in about a second with a `conversation_id` and `status: "running"`. 2. [Read the conversation](/api-reference/v3/conversations/get) with `wait=45` until `status` is no longer `running`. Each call holds up to 45 seconds and returns as soon as the run ends. 3. Read the answer and citations from the last turn. [Fetch documents](/api-reference/v3/conversations/document) the agent wrote, if any. 4. [Send a follow-up](/api-reference/v3/conversations/messages) and poll again. Nothing depends on keeping a connection open: the run continues on Rhizome's side whatever your client does. To cancel one, [stop it](/api-reference/v3/conversations/stop). ## Statuses A conversation's `status` is its latest message's status. | Status | Meaning | | - | - | | `running` | The agent is working on the latest message. Poll again. | | `completed` | The latest turn has an answer. | | `needs_input` | The agent asked a clarifying question instead of answering. The turn's `question` has it; reply with a follow-up message. | | `stopped` | The message was stopped. It is removed from `turns` and not counted against your plan, so the last turn is the previous answer, if any. | | `error` | The run failed. `error` says why. You can send the message again as a follow-up. | ## Answers and citations `answer` is markdown. Citations appear in it as `[1]`, `[2]`, matching the `index` of an entry in the turn's `citations`. Citation numbers continue across the turns of a conversation. A link of the form `doc:` in an answer points at an entry in the conversation's `documents`. Each citation gives the source document's name, dataset, date and page, and a `url` that opens the source in the conversation on rhizomeai.com. ## Retries and idempotency Send an `Idempotency-Key` header with each message to make retries safe. If a request times out and you retry it with the same key, you get the conversation or turn the first request created instead of a second run. Keys are scoped to your account; use a new one, such as a UUID, for each message. Reusing a key with a different message is a `422`. ## Plans and limits Runs use the plan of the API key's owner, as on rhizomeai.com: on a free plan each message counts against the monthly question limit, and a message over the limit is a `402`. Downloading Word, Excel and PowerPoint files needs a paid plan. An account can have 3 conversations running at once, counting those started on rhizomeai.com. A message that would start a fourth is a `429` with code `concurrent_conversations` and a `Retry-After` header; send it again once a run finishes. Request bodies are JSON, up to 1 MB. ## Errors Errors return `{"error": {"code", "message", "field", "request_id"}}`, as on every API v3 endpoint; `field` names the value at fault when there is one. Every response has an `X-Request-Id` header. See [Errors](/errors). | Status | Code | Description | | - | - | - | | 400 | `invalid_request` | A body that isn't JSON, a missing or empty `message`, a bad parameter, or a malformed `Idempotency-Key` | | 401 | `missing_api_key`, `invalid_api_key` | Missing or invalid API key | | 402 | `quota_exhausted` | The free plan's monthly questions are used up | | 403 | `forbidden` | Downloading a Word, Excel or PowerPoint file needs a paid plan | | 404 | `not_found` | No conversation or document with this id in your account | | 409 | `turn_in_flight` | The conversation is still running the previous message | | 409 | `idempotency_key_in_use` | A request with this key is still being processed. Retry shortly. | | 413 | `payload_too_large` | The request body is over 1 MB | | 422 | `idempotency_key_reused` | The key was already used with a different message | | 429 | `concurrent_conversations` | 3 conversations are already running. Retry after `Retry-After` seconds. | | 429 | `rate_limited` | Rate limit exceeded (50 requests/minute) | ## Example ```python Python theme={null} import time import uuid import requests BASE = "https://rhizomeai.com/api/v3/conversations" HEADERS = {"x-api-key": "YOUR_API_KEY"} def ask(message, conversation_id=None): url = f"{BASE}/{conversation_id}/messages" if conversation_id else BASE headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())} response = requests.post(url, headers=headers, json={"message": message}) response.raise_for_status() conversation_id = response.json()["conversation_id"] while True: response = requests.get( f"{BASE}/{conversation_id}", headers=HEADERS, params={"wait": 45} ) response.raise_for_status() conversation = response.json() if conversation["status"] in ("stopped", "error"): raise RuntimeError(conversation["error"] or "The message was stopped.") if conversation["status"] != "running": return conversation conversation = ask("What De Novo requests has the FDA granted this year?") turn = conversation["turns"][-1] print(turn["answer"]) for citation in turn["citations"]: print(f"[{citation['index']}] {citation['name']}") follow_up = ask("Which of them are cardiovascular devices?", conversation["conversation_id"]) print(follow_up["turns"][-1]["answer"]) ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.