> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gumloop.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieve Agent Status
Poll the status of an API-initiated agent interaction. Once the interaction reaches the `COMPLETED` state, the response includes the full conversation messages and the agent's final text response.
## Request
### Headers
```text theme={"dark"}
Authorization: Bearer YOUR_API_KEY
```
### URL Parameters
The interaction ID returned from the [Start Agent](/api-reference/running-an-agent/start-agent) endpoint.
### Query Parameters
Your Gumloop user ID. Required if `project_id` is not provided.
Your team (workspace) ID. Required if `user_id` is not provided.
### Example Request
```bash cURL theme={"dark"}
curl "https://api.gumloop.com/api/v1/agent_status/xYz789AbCdEfGhI?user_id=your_user_id&project_id=your_project_id" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```python Python theme={"dark"}
import requests
url = "https://api.gumloop.com/api/v1/agent_status/xYz789AbCdEfGhI"
headers = {
"Authorization": "Bearer YOUR_API_KEY"
}
params = {
"user_id": "your_user_id",
"project_id": "your_project_id"
}
response = requests.get(url, headers=headers, params=params)
print(response.json())
```
```javascript JavaScript theme={"dark"}
const interactionId = "xYz789AbCdEfGhI";
const params = new URLSearchParams({
user_id: "your_user_id",
project_id: "your_project_id",
});
fetch(
`https://api.gumloop.com/api/v1/agent_status/${interactionId}?${params}`,
{
headers: { Authorization: "Bearer YOUR_API_KEY" },
}
)
.then((response) => response.json())
.then((data) => console.log(data));
```
## Response
### While Processing (200 OK)
When the agent is still working, the response contains only the interaction metadata:
```json theme={"dark"}
{
"interaction_id": "xYz789AbCdEfGhI",
"gummie_id": "abc123DEFghiJKL",
"state": "ASYNC_PROCESSING",
"created_ts": "2026-03-05T10:30:00.000000+00:00"
}
```
### On Completion (200 OK)
When the agent finishes, the response includes the full conversation and a convenience `response` field:
```json theme={"dark"}
{
"interaction_id": "xYz789AbCdEfGhI",
"gummie_id": "abc123DEFghiJKL",
"state": "COMPLETED",
"created_ts": "2026-03-05T10:30:00.000000+00:00",
"messages": [
{
"id": "msg_abc123",
"role": "user",
"content": "Summarize the latest sales report and send it to the team Slack channel",
"timestamp": "2026-03-05T10:30:00.000000",
"parts": []
},
{
"id": "msg_def456",
"role": "assistant",
"timestamp": "2026-03-05T10:30:15.000000",
"parts": [
{
"id": "part_ghi789",
"type": "text",
"text": "I've summarized the latest sales report and posted the summary to the #sales-team Slack channel. Here's what I found..."
},
{
"id": "part_jkl012",
"type": "tool_invocation",
"toolCallId": "tc_mno345",
"toolName": "slack_message_sender",
"toolCallState": "completed",
"result": {
"args": {"channel": "#sales-team", "message": "..."},
"result": "Message sent successfully"
}
}
]
}
],
"response": "I've summarized the latest sales report and posted the summary to the #sales-team Slack channel. Here's what I found..."
}
```
### On Failure (200 OK)
When the agent encounters an error, the response includes an `error_message`:
```json theme={"dark"}
{
"interaction_id": "xYz789AbCdEfGhI",
"gummie_id": "abc123DEFghiJKL",
"state": "FAILED",
"created_ts": "2026-03-05T10:30:00.000000+00:00",
"error_message": "RuntimeError: Agent encountered an error while processing"
}
```
### Response Fields
The unique interaction identifier.
The agent's ID.
Current state of the interaction. One of: `ASYNC_PROCESSING`, `COMPLETED`, `FAILED`.
ISO 8601 timestamp of when the interaction was created.
Full conversation history including the user message and all agent messages with tool call details. Only present when `state` is `COMPLETED`.
The agent's final text response extracted from the last assistant message. This is a convenience field: the same text exists in the `messages` array. Only present when `state` is `COMPLETED`.
Description of what went wrong (truncated to 4096 characters). Only present when `state` is `FAILED`.
### Error Responses
| Status Code | Error | Description |
| ----------- | --------------------------------------------------------------------------------- | --------------------------------------------- |
| 401 | `"Authorization header with Bearer token or api_key query parameter is required"` | No API key provided. |
| 403 | `"unauthorized"` | User doesn't have access to this interaction. |
| 404 | `"interaction_not_found"` | No interaction found with this ID. |
***
## Interaction States
| State | Description | Action |
| ------------------ | --------------------------------------------- | ------------------------------------------------------------------- |
| `ASYNC_PROCESSING` | The agent is actively processing the request. | Wait and poll again (recommended: every 2-5 seconds). |
| `COMPLETED` | The agent has finished. | Read `response` for the text reply, or `messages` for full details. |
| `FAILED` | The agent encountered an error. | Read `error_message` for details. |
***
## Message Structure
When the interaction completes, the `messages` array contains the full conversation. Each message has the following structure:
### User Message
```json theme={"dark"}
{
"id": "msg_xxxxxxxxxxxx",
"role": "user",
"content": "The message you sent to the agent",
"timestamp": "2026-03-05T10:30:00.000000",
"parts": []
}
```
### Assistant Message
Assistant messages contain `parts` instead of `content`. Each part represents a piece of the response:
**Text Part:**
```json theme={"dark"}
{
"id": "part_xxxxxxxxxxxx",
"type": "text",
"text": "The agent's text response content..."
}
```
**Tool Invocation Part:**
```json theme={"dark"}
{
"id": "part_xxxxxxxxxxxx",
"type": "tool_invocation",
"toolCallId": "tc_xxxxxxxxxxxx",
"toolName": "slack_message_sender",
"toolCallState": "completed",
"result": {
"args": { "channel": "#sales", "message": "..." },
"result": "Message sent successfully"
}
}
```
**File Part:**
```json theme={"dark"}
{
"id": "part_xxxxxxxxxxxx",
"type": "file",
"file": { }
}
```
**Error Part:**
```json theme={"dark"}
{
"id": "part_xxxxxxxxxxxx",
"type": "error",
"error": "Description of error"
}
```
Messages are sanitized to include only safe fields. Message-level fields: `id`, `role`, `timestamp`, `parts`, `content`. Part-level fields: `id`, `type`, `text`, `reasoning`, `toolCallId`, `toolName`, `toolCallState`, `result`, `error`, `file`. Result-level fields: `args`, `result`.
***
## Polling Best Practices
* **Poll interval**: 2-5 seconds is recommended. Avoid polling more frequently than every 1 second.
* **Timeout**: Set a reasonable timeout (e.g., 5-10 minutes) depending on your agent's expected workload.
* **Backoff**: Consider exponential backoff if you're making many concurrent requests.
* **Resumable**: If your client disconnects, you can resume polling with the same `interaction_id`. Each call to `/start_agent` creates a new interaction, so there's no risk of duplicate processing.
* **Use `response` for simple integrations**: It contains just the agent's final text. Use `messages` when you need tool call details or the full conversation.