Get Execution

GET https://app.doclo.ai/api/v1/runs/{executionId}

Authorization: Bearer dc_live_your_api_key

{
  "id": "exec_abc123def456",
  "flowId": "invoice-extractor",
  "version": "1.2.0",
  "status": "running",
  "progress": {
    "step": "extract",
    "percentage": 65
  },
  "createdAt": "2024-02-20T15:30:00Z",
  "metadata": {
    "customerId": "cust_123"
  }
}

{
  "id": "exec_abc123def456",
  "flowId": "invoice-extractor",
  "version": "1.2.0",
  "status": "completed",
  "createdAt": "2024-02-20T15:30:00Z",
  "completedAt": "2024-02-20T15:30:12Z",
  "output": {
    "invoiceNumber": "INV-2024-001",
    "date": "2024-02-15",
    "vendor": {
      "name": "Acme Corporation",
      "address": "123 Business St"
    },
    "total": 1627.50
  },
  "metrics": {
    "durationMs": 12340,
    "pageCount": 2,
    "creditsUsed": 4
  },
  "metadata": {
    "customerId": "cust_123"
  }
}

{
  "id": "exec_abc123def456",
  "flowId": "invoice-extractor",
  "version": "1.2.0",
  "status": "failed",
  "createdAt": "2024-02-20T15:30:00Z",
  "completedAt": "2024-02-20T15:30:05Z",
  "error": {
    "code": "EXTRACTION_FAILED",
    "message": "Unable to extract structured data from document",
    "step": "extract"
  },
  "metadata": {
    "customerId": "cust_123"
  }
}

{
  "id": "exec_abc123def456",
  "flowId": "invoice-extractor",
  "status": "completed",
  "output": { ... },
  "artifacts": {
    "parse": {
      "pageCount": 2,
      "wordCount": 450,
      "documentIR": { ... }
    },
    "extract": {
      "tokensUsed": 1250,
      "model": "gpt-4.1"
    }
  }
}

curl https://app.doclo.ai/api/v1/runs/exec_abc123def456 \
  -H "Authorization: Bearer dc_live_your_api_key"

curl "https://app.doclo.ai/api/v1/runs/exec_abc123def456?include=artifacts,metrics" \
  -H "Authorization: Bearer dc_live_your_api_key"

async function pollExecution(executionId: string): Promise<ExecutionResult> {
  const maxAttempts = 60;
  const pollInterval = 2000;

  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const response = await fetch(
      `https://app.doclo.ai/api/v1/runs/${executionId}`,
      {
        headers: {
          'Authorization': `Bearer ${process.env.DOCLO_API_KEY}`
        }
      }
    );

    const result = await response.json();

    switch (result.status) {
      case 'completed':
        return result;
      case 'failed':
        throw new Error(`Execution failed: ${result.error.message}`);
      case 'cancelled':
        throw new Error('Execution was cancelled');
      case 'pending':
      case 'running':
        // Still processing, wait and retry
        console.log(`Status: ${result.status}, Progress: ${result.progress?.percentage || 0}%`);
        await new Promise(resolve => setTimeout(resolve, pollInterval));
        break;
    }
  }

  throw new Error('Polling timeout exceeded');
}

// Usage
const executionId = 'exec_abc123def456';
const result = await pollExecution(executionId);
console.log('Output:', result.output);

const response = await fetch(
  `https://app.doclo.ai/api/v1/runs/${executionId}`,
  {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  }
);

const { status, progress } = await response.json();

if (status === 'running') {
  console.log(`Processing: ${progress.step} (${progress.percentage}%)`);
}

// Exponential backoff polling
async function pollWithBackoff(executionId: string) {
  let interval = 2000;
  const maxInterval = 10000;
  const timeout = 600000; // 10 minutes
  const startTime = Date.now();

  while (Date.now() - startTime < timeout) {
    const result = await getExecution(executionId);

    if (result.status === 'completed' || result.status === 'failed') {
      return result;
    }

    await new Promise(resolve => setTimeout(resolve, interval));
    interval = Math.min(interval * 1.5, maxInterval);
  }

  throw new Error('Timeout');
}