Skip to main content
GET
/
agent_status
/
{interaction_id}
Retrieve Agent Status
curl --request GET \
  --url https://api.gumloop.com/api/v1/agent_status/{interaction_id} \
  --header 'Authorization: Bearer <token>'
{
  "interaction_id": "<string>",
  "gummie_id": "<string>",
  "state": "<string>",
  "created_ts": "<string>",
  "messages": [
    {}
  ],
  "response": "<string>",
  "error_message": "<string>"
}
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

Authorization: Bearer YOUR_API_KEY

​
URL Parameters

​
interaction_id
string
required
The interaction ID returned from the Start Agent endpoint.

​
Query Parameters

​
user_id
string
Your Gumloop user ID. Required if project_id is not provided.
​
project_id
string
Your team (workspace) ID. Required if user_id is not provided.

​
Example Request

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"

​
Response

​
While Processing (200 OK)

When the agent is still working, the response contains only the interaction metadata: 
{
  "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: 
{
  "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: 
{
  "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

​
interaction_id
string
The unique interaction identifier.
​
gummie_id
string
The agent’s ID.
​
state
string
Current state of the interaction. One of: ASYNC_PROCESSING, COMPLETED, FAILED.
​
created_ts
string
ISO 8601 timestamp of when the interaction was created.
​
messages
array
Full conversation history including the user message and all agent messages with tool call details. Only present when state is COMPLETED.
​
response
string
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.
​
error_message
string
Description of what went wrong (truncated to 4096 characters). Only present when state is FAILED.

​
Error Responses

Status CodeErrorDescription
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

StateDescriptionAction
ASYNC_PROCESSINGThe agent is actively processing the request.Wait and poll again (recommended: every 2-5 seconds).
COMPLETEDThe agent has finished.Read response for the text reply, or messages for full details.
FAILEDThe 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

{
  "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: 
{
  "id": "part_xxxxxxxxxxxx",
  "type": "text",
  "text": "The agent's text response content..."
}
Tool Invocation Part: 
{
  "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: 
{
  "id": "part_xxxxxxxxxxxx",
  "type": "file",
  "file": { }
}
Error Part: 
{
  "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.