Create a Research Agent session

Start a stateful Research Agent session. Elicit investigates the query asynchronously, reports its activity as structured events, and may produce downloadable artifacts.

The response returns immediately with a sessionId. Use the events endpoint to follow the research, then send messages to refine or continue it. The session is also available at the returned url.

This endpoint is in early access. It returns 404 not_found unless the Research Agent API has been enabled for the authenticated account or organization.

End-to-end workflow

A full research task may involve several requests against a single session. To drive it end to end:

1. (Optional) Upload files. POST /api/v2/files, PUT the bytes to the presigned URL, and keep each file_id (see the Upload endpoint).
2. Create the session. POST /api/v2/sessions/agents with your query and any attachments. The response is immediate with status: "processing" and a sessionId.
3. Poll for activity. GET /api/v2/sessions/agents/:sessionId/events. Pass the returned cursor unchanged on each subsequent poll to receive immutable event occurrences not observed at that checkpoint. Append them in response order and deduplicate retries by eventId. Poll every 3–10 seconds while the top-level status is processing.
4. Detect idle. The agent is ready for another request when a session_idle event appears and the top-level status returns to completed. For a Research Agent session, completed means idle and awaiting input — not that the session is permanently closed. Watch for these events along the way:
   • question — the agent needs input; answer it with a follow-up message.
   • error — the agent encountered an error; retryable indicates whether resending is worthwhile.
   • session_paused — the account hit its usage limit; the status becomes pausedForInsufficientQuota. Resolve the limit, then resume the session via POST /api/v2/sessions/:sessionId/resume (or the Elicit web interface) before continuing.
5. Send a follow-up. POST /api/v2/sessions/agents/:sessionId/messages with your message (and any attachments). Correlate the returned messageId with the matching user_message event, then return to step 3.
6. Retrieve artifacts. GET /api/v2/sessions/agents/:sessionId/artifacts to list what the agent produced: files appear under artifacts (GET .../artifacts/:artifactId/download for a short-lived presigned download URL — treat it as a credential), and interactive outputs (tables, prose, presentations, figures) appear under deliveredOutputs (GET .../artifacts/:artifactId/content for their contents).
7. (Optional) Stop early. POST /api/v2/sessions/agents/:sessionId/stop to interrupt a running turn, then poll the events endpoint for the session_stopped event.

Session status

The list, detail, and events endpoints all report the same top-level status:

• processing — the agent is working (or the session has not started yet).
• completed — idle and awaiting input; the latest work finished successfully.
• failed — the latest work ended with an error.
• pausedForInsufficientQuota — paused at the account usage limit; resume once the limit clears.
• unknown — status could not be determined (legacy sessions only).

All errors return the standard { "error": { "code", "message" } } envelope.

Example

# Minimal
curl -X POST https://elicit.com/api/v2/sessions/agents \
  -H "Authorization: Bearer elk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query":"What are the effects of GLP-1 receptor agonists on cardiovascular outcomes?"}'

# With an uploaded file attached to the initial turn
curl -X POST https://elicit.com/api/v2/sessions/agents \
  -H "Authorization: Bearer elk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query":"Summarize the attached trial and compare it to the current literature.","attachments":[{"file_id":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"}]}'