---
title: "Send a message to a Research Agent session"
method: POST
path: "/sessions/agents/{sessionId}/messages"
tags: ["Research Agent"]
---

# Send a message to a Research Agent session

`POST /sessions/agents/{sessionId}/messages`

## Request

- Base URL: `https://elicit.com/api/v2`
- URL: `https://elicit.com/api/v2/sessions/agents/{sessionId}/messages`
- Auth: HTTP bearer

Insert a follow-up message and start another asynchronous turn. Use messages to refine a result, answer the agent, redirect the research, or request another artifact.

The response includes a `messageId`. The corresponding `user_message` event carries the same value, allowing the client to confirm delivery.

Attach previously uploaded files by including their `file_id`s in the `attachments` array (see the Upload endpoint). A session can hold at most 100 distinct files totaling 10GB across all turns; files already attached to this session can be referenced again without consuming another slot.

If the session is paused for insufficient quota, resolve the usage limit and resume it via `POST /api/v2/sessions/:sessionId/resume` (or the Elicit web interface) before sending another message.

### Example

```bash
curl -X POST https://elicit.com/api/v2/sessions/agents/{sessionId}/messages \
  -H "Authorization: Bearer elk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"message":"Focus on randomized controlled trials only."}'
```

## Path parameters

- `sessionId` string, uuid, required

## Request body

- object
  - `message` string, required: The message to insert into the running research agent session.
  - `attachments` object[]: Files to attach to this turn, each referencing a file_id from POST /api/v2/files. A session can hold at most 100 distinct files totaling 10GB across all turns. An already-attached file can be referenced again in the same session without consuming additional capacity, but not claimed by another session or import. Duplicate file_ids within one request are rejected.
    - `file_id` string, uuid, required: The file_id returned by POST /api/v2/files for a previously uploaded file.

## Response `202`

Message accepted. The session is processing another turn.

- PostAgentSessionMessageResponse
  - `sessionId` string, required: Unique identifier for the research agent session.
  - `status` 'processing', required: The session is processing the inserted message.
  - `messageId` string, required: Identifier of the inserted message. Correlate it with the messageId on the matching user_message event.
  - `url` string, required: URL to view the session in the Elicit web interface. Only the owner can continue it.

## Other responses

- `400`: Invalid request: query/message must contain 1–20,000 characters and attachments must satisfy the schema (invalid_request). Attachment checks can also return file_not_uploaded if the upload cannot be verified, or file_size_mismatch if the uploaded byte length differs from size_bytes.
- `401`: Authentication failed. The API key is missing, invalid, revoked, or expired.
- `402`: Insufficient quota. For credits-based accounts, and for organization members with a weekly workflow-run limit, `error.details.reason` says why (`credits_exhausted` or `spend_limit_reached`) and `error.details.resetsAt` when the block lifts.
- `403`: API access is not available on your current plan. Upgrade to Pro or above to use the API.
- `404`: The session does not exist or is not owned by you (session_not_found), or an attachment is missing or belongs to another user (attachment_not_found).
- `409`: The session failed (session_failed) or is paused for insufficient quota (session_paused); an attachment is claimed elsewhere (attachment_already_used); or the session's file count or total upload size cap would be exceeded (too_many_files, total_upload_size_exceeded).
- `410`: An unclaimed upload expired. Stage and upload it again before attaching it.
- `429`: Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.
- `500`: An unexpected error occurred. Retry reads with backoff; before retrying a write, check whether it took effect. See Error Handling for retry guidance.

## Changes

- **2026-10-20** `d75d82fcc944`: 1 info
  - the `message` request property's maxLength was increased from `2000` to `20000`
- **2026-10-16** `22847bf7e65d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/elicitlabs/apis/elicit-labs-api/changes/sessions/agents/:sessionId/messages/post.md)

---

[API](https://skmtc.dev/elicitlabs/apis/elicit-labs-api.md) - [All operations](https://skmtc.dev/elicitlabs/apis/elicit-labs-api/llms.txt) - [OpenAPI document](https://skmtc.dev/elicitlabs/apis/elicit-labs-api/revisions/cbbe29509d04?raw)