Get async tool execution status and result

GET

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

const url = 'https://dashboard.quantcdn.io/api/v3/organizations/example/ai/tools/executions/exec_0123456789abcdef0123456789abcdef';
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/executions/exec_0123456789abcdef0123456789abcdef \
  --header 'Authorization: Bearer <token>'

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

BearerAuth

Parameters

Path Parameters

organisation

required

string

The organisation ID

executionId

required

string

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

Example

exec_0123456789abcdef0123456789abcdef

Tool execution identifier

Responses

200

Tool execution status retrieved successfully

application/json

object

executionId

required

string

toolName

required

string

status

required

Execution status: pending, running, complete, or failed

string

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>

error

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

string

createdAt

required

Unix timestamp when execution was created

integer

startedAt

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

integer

completedAt

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

integer

duration

Execution duration in seconds (if completed)

number

Example

{
  "executionId": "exec_abc123def456",
  "toolName": "generate_image",
  "status": "complete",
  "result": {
    "images": [
      "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
    ],
    "s3Urls": [
      "https://au-stg-ai-images.s3.amazonaws.com/generated/exec_abc123..."
    ]
  },
  "error": "Image generation failed: Invalid prompt",
  "createdAt": 1730271600,
  "startedAt": 1730271601,
  "completedAt": 1730271612,
  "duration": 11
}

403

Access denied

404

Execution not found (may have expired after 24h)

application/json

object

error

string

executionId

string

Example

{
  "error": "Execution not found",
  "executionId": "exec_abc123def456"
}

500

Failed to retrieve execution status