Get Act request

GET

act

requests

{actRequestId}

Get Act request

curl --request GET \
  --url https://api.darwin.so/api/v3/act/requests/{actRequestId} \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.darwin.so/api/v3/act/requests/{actRequestId}', 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.darwin.so/api/v3/act/requests/{actRequestId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$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.darwin.so/api/v3/act/requests/{actRequestId}"

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

	req.Header.Add("x-api-key", "<api-key>")

	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.darwin.so/api/v3/act/requests/{actRequestId}")

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

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

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

{
  "type": "request",
  "actRequestId": "<string>",
  "searchId": "<string>",
  "status": "pending",
  "createdAt": "2023-11-07T05:31:56Z",
  "threads": [
    {
      "agentId": "<string>",
      "capabilityId": "<string>",
      "threadId": "<string>",
      "messageId": "<string>",
      "errorCode": "<string>",
      "state": {
        "thread": "<string>",
        "messages": [
          {
            "message": "<string>",
            "from": "you",
            "content": [
              {
                "type": "text",
                "text": "<string>"
              }
            ],
            "status": "accepted",
            "createdAt": "2023-11-07T05:31:56Z",
            "type": "message"
          }
        ],
        "actions": [
          {
            "action": "<string>",
            "capability": "<string>",
            "request": "<string>",
            "status": "awaiting_confirmation",
            "cancellationRequested": true,
            "accepted": true
          }
        ],
        "requests": [
          {
            "request": "<string>",
            "action": "<string>",
            "status": "pending",
            "type": "action_request",
            "capability": "<string>",
            "arguments": {},
            "account": "<string>"
          }
        ],
        "cursor": "<string>",
        "hasMore": true,
        "archived": true,
        "needsAttention": true,
        "errors": [
          {
            "event": "<string>",
            "code": "<string>",
            "retryable": true,
            "createdAt": "2023-11-07T05:31:56Z",
            "action": "<string>"
          }
        ]
      }
    }
  ]
}

Use the same authorized caller that started the work. An Act request groups the child thread receipts from a start. Its status describes accepting those starts; it does not prove the providers completed the work.

Thread-state inclusion is pending deployment. Until it is released, existing clients can continue using their current thread reader.

Set includeThreadState=true to read each child thread’s current messages, actions, and pending requests in threads[].state. Darwin checks the live grant and access to every thread. Failed starts have no thread state. Without this option, the response remains the original receipt.

curl 'https://api.darwin.so/api/v3/act/requests/ACT_REQUEST_ID?includeThreadState=true' \
  -H "x-api-key: $DARWIN_API_KEY"

Each thread’s state contains messages, actions, requests, cursor, and hasMore. To read the next page, send the same Act request ID with includeThreadState=true, that child’s threadId, and its cursor. limit is 1–100, default 20 per thread. A thread from another Act request is rejected. Continue the selected child through Act, using its threadId. Copy authentication, payment and approval request IDs from that child’s state.requests; text is never a substitute for consent or payment.

Authorizations

x-api-key

string

header

required

Path Parameters

actRequestId

string

required

Query Parameters

includeThreadState

boolean

default:false

Include authorized child thread messages, actions and pending requests.

threadId

string

Read state for this child thread only. Must belong to the Act request.

cursor

string

Read the next message page for threadId. Requires includeThreadState=true.

limit

integer

default:20

Required range: 1 <= x <= 100

Response

Act request receipt and optional live, authorized child thread state.

type

string

required

Allowed value: "request"

actRequestId

string

required

Required string length: 1 - 200

Pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$

searchId

string | null

required

Required string length: 1 - 200

Pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$

status

enum<string>

required

Act Request handoff status only. Completed means thread receipts were created; read each thread for action confirmation and provider result.

Available options:

pending,

completed,

partial,

failed

createdAt

string<date-time>

required

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

threads

object[]

required

Required array length: 1 - 8 elements

Show child attributes

Last modified on October 10, 2026

Get Act request

curl --request GET \
  --url https://api.darwin.so/api/v3/act/requests/{actRequestId} \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.darwin.so/api/v3/act/requests/{actRequestId}', 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.darwin.so/api/v3/act/requests/{actRequestId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$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.darwin.so/api/v3/act/requests/{actRequestId}"

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

	req.Header.Add("x-api-key", "<api-key>")

	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.darwin.so/api/v3/act/requests/{actRequestId}")

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

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

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

{
  "type": "request",
  "actRequestId": "<string>",
  "searchId": "<string>",
  "status": "pending",
  "createdAt": "2023-11-07T05:31:56Z",
  "threads": [
    {
      "agentId": "<string>",
      "capabilityId": "<string>",
      "threadId": "<string>",
      "messageId": "<string>",
      "errorCode": "<string>",
      "state": {
        "thread": "<string>",
        "messages": [
          {
            "message": "<string>",
            "from": "you",
            "content": [
              {
                "type": "text",
                "text": "<string>"
              }
            ],
            "status": "accepted",
            "createdAt": "2023-11-07T05:31:56Z",
            "type": "message"
          }
        ],
        "actions": [
          {
            "action": "<string>",
            "capability": "<string>",
            "request": "<string>",
            "status": "awaiting_confirmation",
            "cancellationRequested": true,
            "accepted": true
          }
        ],
        "requests": [
          {
            "request": "<string>",
            "action": "<string>",
            "status": "pending",
            "type": "action_request",
            "capability": "<string>",
            "arguments": {},
            "account": "<string>"
          }
        ],
        "cursor": "<string>",
        "hasMore": true,
        "archived": true,
        "needsAttention": true,
        "errors": [
          {
            "event": "<string>",
            "code": "<string>",
            "retryable": true,
            "createdAt": "2023-11-07T05:31:56Z",
            "action": "<string>"
          }
        ]
      }
    }
  ]
}

Search

Act

Account

Get Act request

Authorizations

Path Parameters

Query Parameters

Response