Skip to content
QuantCDN

Get async tool execution status and result

GET
/api/v3/organizations/{organisation}/ai/tools/executions/{executionId}

Retrieves the status and result of an async tool execution. Used for polling long-running tools like image generation. * * Async Tool Execution Pattern: * This endpoint enables a polling pattern for long-running tools that would otherwise hit API Gateway’s 30-second timeout. * * Flow: * 1. AI requests tool use (e.g., generate_image) * 2. Chat API returns toolUse with execution tracking info * 3. Client starts polling this endpoint with the executionId * 4. When status === 'complete', retrieve result and send back to AI * 5. AI incorporates result into final response * * Status Values: * - pending: Tool execution queued, not yet started * - running: Tool is currently executing * - complete: Tool execution finished successfully, result available * - failed: Tool execution failed, error available * * Polling Recommendations: * - Poll every 2-3 seconds for image generation * - Exponential backoff for other tools (start 1s, max 5s) * - Stop polling after 5 minutes (consider failed) * - Auto-cleanup after 24 hours (TTL) * * Use Cases: * - Image generation (10-15s typical runtime) * - Video processing * - Large file uploads/downloads * - Complex database queries * - External API calls with high latency

Authorizations

Parameters

Path Parameters

organisation
required
string

The organisation ID

executionId
required
string
/^exec_[a-f0-9]{32}$/ 
exec_abc123def456

Tool execution identifier

Responses

200

Tool execution status retrieved successfully

object
executionId
required
string
exec_abc123def456
toolName
required
string
generate_image
status
required
string
Allowed values: pending running complete failed
result

Tool execution result (only present when status=‘complete’). Structure varies by tool type.

object
images

For image generation: Array of base64-encoded data URIs for inline display/preview

Array<string>
s3Urls

For image generation: Array of signed S3 URLs for high-quality downloads (expire after 1 hour)

Array<string>
{
  "images": [
    "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  ],
  "s3Urls": [
    "https://au-stg-ai-images.s3.amazonaws.com/generated/exec_abc123..."
  ]
}
error

Error message (only present when status=‘failed’)

string
Image generation failed: Invalid prompt
createdAt
required

Unix timestamp when execution was created

integer
1730271600
startedAt

Unix timestamp when execution started (if status >= ‘running’)

integer
1730271601
completedAt

Unix timestamp when execution completed (if status in [‘complete’, ‘failed’])

integer
1730271612
duration

Execution duration in seconds (if completed)

number
11

403

Access denied

404

Execution not found (may have expired after 24h)

object
error
string
Execution not found
executionId
string
exec_abc123def456

500

Failed to retrieve execution status