Retrieve Agent Status

curl --request GET \
  --url https://api.gumloop.com/api/v1/agent_status/{interaction_id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.gumloop.com/api/v1/agent_status/{interaction_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.gumloop.com/api/v1/agent_status/{interaction_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gumloop.com/api/v1/agent_status/{interaction_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gumloop.com/api/v1/agent_status/{interaction_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.gumloop.com/api/v1/agent_status/{interaction_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "interaction_id": "<string>",
  "gummie_id": "<string>",
  "state": "<string>",
  "created_ts": "<string>",
  "messages": [
    {}
  ],
  "response": "<string>",
  "error_message": "<string>"
}

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>'

import requests

url = "https://api.gumloop.com/api/v1/agent_status/{interaction_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.gumloop.com/api/v1/agent_status/{interaction_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gumloop.com/api/v1/agent_status/{interaction_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gumloop.com/api/v1/agent_status/{interaction_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.gumloop.com/api/v1/agent_status/{interaction_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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

string

required

The interaction ID returned from the Start Agent endpoint.

Query Parameters

string

Your Gumloop user ID. Required if project_id is not provided.

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"

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())

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:

{
  "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

string

The unique interaction identifier.

string

The agent’s ID.

string

Current state of the interaction. One of: ASYNC_PROCESSING, COMPLETED, FAILED.

string

ISO 8601 timestamp of when the interaction was created.

array

Full conversation history including the user message and all agent messages with tool call details. Only present when state is COMPLETED.

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.

string

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

{
  "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.

Core Concepts

SDKs

Agents

Sessions

Skills

Artifacts

MCP

Evaluations

Brain

Teams

Chat completions

Models

Retrieving Automations

File Operations

Enterprise Organization

Running Flows

Retrieve Agent Status

Request

Headers

URL Parameters

Query Parameters

Example Request

Response

While Processing (200 OK)

On Completion (200 OK)

On Failure (200 OK)

Response Fields

Error Responses

Interaction States

Message Structure

User Message

Assistant Message

Polling Best Practices

​Request

​Headers

​URL Parameters

​Query Parameters

​Example Request

​Response

​While Processing (200 OK)

​On Completion (200 OK)

​On Failure (200 OK)

​Response Fields

​Error Responses

​Interaction States

​Message Structure

​User Message

​Assistant Message

​Polling Best Practices

Request

Headers

URL Parameters

Query Parameters

Example Request

Response

While Processing (200 OK)

On Completion (200 OK)

On Failure (200 OK)

Response Fields

Error Responses

Interaction States

Message Structure

User Message

Assistant Message

Polling Best Practices