Get Tool Orchestration Status (Async Tool Polling)

GET

/api/v3/organizations/{organisation}/ai/tools/orchestrations/{orchestrationId}

const url = 'https://dashboard.quantcdn.io/api/v3/organizations/example/ai/tools/orchestrations/orch_abc123def456789012345678901234';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://dashboard.quantcdn.io/api/v3/organizations/example/ai/tools/orchestrations/orch_abc123def456789012345678901234 \
  --header 'Authorization: Bearer <token>'

Retrieves the status and synthesized result of a multi-tool async execution orchestration. * * Note: This endpoint is for async tool execution polling (/tools/orchestrations). * For durable batch processing orchestrations, see GET /orchestrations endpoints. * * Orchestration Pattern: * When the AI requests multiple async tools simultaneously, an orchestration is created * to track all tool executions and synthesize their results into a single coherent response. * * Flow: * 1. AI requests multiple async tools (e.g., image generation + web search) * 2. Chat API creates orchestration and returns orchestrationId * 3. Tool Orchestrator Lambda polls all async tools * 4. When all tools complete, Orchestrator synthesizes results using AI * 5. Client polls this endpoint and receives final synthesized response * * Status Values: * - pending: Orchestration created, tools not yet started * - polling: Orchestrator is actively polling async tools * - synthesizing: All tools complete, AI is synthesizing response * - complete: Orchestration finished, synthesizedResponse available * - failed: Orchestration failed, error available * * Polling Recommendations: * - Poll every 2 seconds * - Maximum poll time: 10 minutes * - Orchestrator handles tool polling internally * * Benefits over individual polling: * - Single poll endpoint for multiple async tools * - AI synthesizes all results into coherent response * - Answers the original user question, not just tool summaries

Authorizations

BearerAuth

Parameters

Path Parameters

organisation

required

string

The organisation ID

orchestrationId

required

string

/^orch_[a-f0-9]{32}$/

Example

orch_abc123def456789012345678901234

Orchestration identifier for aggregated async tool executions

Responses

200

Orchestration status retrieved successfully

application/json

object

orchestrationId

required

Unique orchestration identifier

string

status

required

Current orchestration status

string

Allowed values: pending waiting_tools synthesizing complete failed

toolCount

required

Total number of async tools in this orchestration

integer

completedTools

Number of tools that have completed

integer

result

AI-synthesized response combining all tool results (only present when status=complete)

string

tools

Status of individual tool executions

Array<object>

object

executionId

string

toolName

string

status

string

Allowed values: pending running complete failed

result

Tool result (if complete)

object

error

Error message (if failed)

string

error

Error message (only present when status=failed)

string

createdAt

required

When orchestration was created

string format: date-time

completedAt

When orchestration completed (if status in complete or failed)

string format: date-time

duration

Seconds from creation to completion (present only once completed)

integer

Example

{
  "orchestrationId": "orch_abc123def456789012345678901234",
  "status": "pending",
  "toolCount": 2,
  "completedTools": 2,
  "result": "Based on the image I generated and the web research...",
  "tools": [
    {
      "executionId": "exec_abc123def456",
      "toolName": "generate_image",
      "status": "pending"
    }
  ],
  "duration": 19
}

403

Access denied

404

Orchestration not found (may have expired after 24h)

application/json

object

error

string

orchestrationId

string

Example

{
  "error": "Orchestration not found",
  "orchestrationId": "orch_abc123def456789012345678901234"
}

500

Failed to retrieve orchestration status