REST API - Kadoa Documentation

The REST API gives you complete control over when and how you retrieve your extracted data. Perfect for batch processing, scheduled jobs, or on-demand access.

Basic Usage

Get Latest Data

Retrieve the most recent data from a workflow: View full API reference →

GET https://api.kadoa.com/v4/workflows/{workflowId}/data

{
  "data": [
    {
      "id": "123",
      "title": "Product Name",
      "price": 99.99,
      "extractedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "metadata": {
    "workflowId": "workflow-123",
    "runId": "run-456",
    "totalRecords": 150,
    "hasMore": false
  }
}

Pagination and Filtering

Handle Large Datasets

Use pagination for efficient data retrieval:

GET https://api.kadoa.com/v4/workflows/{workflowId}/data?limit=100&offset=0

Filtering Options

Target specific data with query parameters:

Date Range: ?startDate=2024-01-01&endDate=2024-01-31
Status Filter: ?status=success
Changes Only: ?changesOnly=true
Fields: ?fields=title,price,extractedAt

Example with Filters

GET https://api.kadoa.com/v4/workflows/{workflowId}/data?startDate=2024-01-01&changesOnly=true&limit=50

Data Formats

JSON (Default)

Standard JSON format, perfect for modern applications:

{
  "data": [...],
  "metadata": {...}
}

CSV Format

Add Accept: text/csv header for CSV output:

// GET /v4/workflows/{workflowId}/data
// Headers: Accept: text/csv, x-api-key: YOUR_API_KEY

Parquet option

Create a signed URL for workflow data as a typed Parquet file: View full API reference →

GET https://api.kadoa.com/v4/workflows/{workflowId}/data/export?format=parquet

Use Parquet when you want to load Kadoa output directly into analytical tools such as DuckDB, Spark, Polars, Snowflake, BigQuery, or pandas. The export endpoint materializes the requested result set and returns a signed url. Pass runId to export a specific historical run:

curl "https://api.kadoa.com/v4/workflows/{workflowId}/data/export?format=parquet&runId={runId}" \
  -H "x-api-key: YOUR_API_KEY"

Filtering, sorting, and row selection use the same query parameters as CSV and JSON exports. For direct streaming of the complete run artifact, use GET /v4/workflows/{workflowId}/data/parquet. Typed columns are preserved where the workflow schema provides native types, including booleans, numbers, dates, timestamps, JSON-compatible objects, and arrays. Older workflow runs may still reflect the type information available when that run was produced.

Error Handling

Common HTTP Status Codes

Code	Meaning	Action
200	Success	Process data normally
400	Bad Request	Check query parameters
401	Unauthorized	Verify API key
404	Not Found	Check workflow ID
429	Rate Limited	Wait and retry
500	Server Error	Contact support

API Reference

For complete API documentation, see:

​Basic Usage

​Get Latest Data

​Pagination and Filtering

​Handle Large Datasets

​Filtering Options

​Example with Filters

​Data Formats

​JSON (Default)

​CSV Format

​Parquet option

​Error Handling

​Common HTTP Status Codes

​API Reference