API & webhooks
Everything the console does, it does through the same REST API you can call. Authenticate with a workspace API key, trigger runs, read results, and subscribe to outbound webhooks for workspace events.
- Read
- 6 min
- Module
- API
API keys
Keys are created under Settings → API keys and are scoped to a single workspace. The secret is shown once, at creation — only a hash is stored, so a lost key is rotated, not recovered. Each key carries a role, which means an integration can be given viewer rights rather than the rights of whoever created it.
Authenticating
Send the key as a bearer token. The API is versioned in the path; breaking changes get a new version rather than mutating the current one.
curl -X POST https://api.datarunner.app/api/v1/queries/{queryId}/run \
-H "Authorization: Bearer dr_live_…" \
-H "Content-Type: application/json" \
-d '{ "parameters": { "since": "2026-07-01" } }'What you can call
| Area | Typical use |
|---|---|
| Queries | Run a saved query and read the result set inline |
| Reports & schedules | Trigger a report out of band; pause or resume a schedule during a deploy |
| Runs & history | Poll the status of an execution, fetch logs |
| Monitors & hosts | Read current status, open and resolve incidents |
| Metrics | Query the semantic layer for a defined number |
| Contacts & campaigns | Sync an audience from your own system |
| Forms | Submit from your own frontend instead of the embed |
Outbound webhooks
Rather than polling, subscribe to events. Endpoints are registered under Settings → Webhooks with a list of event types; each delivery is signed so you can verify it came from DataRunner and not from someone who guessed your URL.
| Event | Fires when |
|---|---|
run.completed | Any execution finishes, successfully or not |
run.failed | An execution ends in error |
report.delivered | A delivery route completes |
watch.triggered | A watch condition matched new rows |
monitor.incident_opened | A monitor crossed into failure |
monitor.incident_resolved | A monitor recovered |
Embedding
Dashboards and status pages can be embedded in your own product using a workspace embed key. The embedded view carries no session and is scoped to the single resource, so it cannot be walked back into the console.