API Reference

Use these endpoints to export execution data to your own systems, poll for job completion, or monitor SLA compliance.

In This Section

Execution Metrics — Job runs, model executions, daily stats, and per-model performance
Examples — Polling scripts, SLA checks, and regression detection

Authentication

All API requests require two headers:

Header	Value	Description
`Authorization`	`Bearer dctl_...`	API token generated from your organization settings
`X-Organization-ID`	`org-xxxxxxxx`	Your organization ID

Creating an API Token

Generate a token from the dagctl web UI under Settings > Authentication, then select the API Tokens tab and click Create Token. The token is displayed once — copy it immediately.

Note

API tokens have full organization access. Store them securely and rotate them periodically.

Example Request

curl -s "https://api.dagctl.com/api/v1/projects/${PROJECT_ID}/runs?limit=10" \
  -H "Authorization: Bearer ${DAGCTL_TOKEN}" \
  -H "X-Organization-ID: ${ORG_ID}"

Base URL

All endpoints are prefixed with /api/v1.

Conventions

Pagination

Paginated endpoints accept page and limit query parameters:

Parameter	Type	Default	Max	Description
`page`	integer	1	-	Page number (1-indexed)
`limit`	integer	varies	500	Results per page

Paginated responses include:

{
  "total": 142,
  "page": 1,
  "limit": 50,
  "total_pages": 3
}

Date Formats

Format	Used For	Example
RFC3339	Timestamps and `updated_after` filter	`2026-02-26T00:00:00Z`
YYYY-MM-DD	Date range filters (`start_date`, `end_date`)	`2026-02-26`

Nullable Fields and `omitempty`

Nullable fields are omitted from the JSON response when their value is null. They do not appear as "field": null — the key is absent entirely.

Fields affected by this behavior:

cronjob_name — absent for manually triggered runs
end_time — absent for in-progress runs
duration_seconds — absent for in-progress runs
error_message — absent when no error occurred
pod_name — absent before pod scheduling

Your polling client should handle missing keys, not null values.