Skip to main content
POST
/
api
/
v1
/
tap
/
run
Run a tap
curl --request POST \
  --url http://localhost:8080/api/v1/tap/run \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "<string>",
  "mode": "test",
  "params": {
    "since": "2026-05-01",
    "until": "2026-05-02"
  }
}
'
{
  "tap": "<string>",
  "description": "<string>",
  "targetPipeline": "<string>",
  "persisted": true,
  "publisherToken": "<string>",
  "pipelineTokens": [
    "<string>"
  ],
  "records": [
    {}
  ],
  "recordCount": 123,
  "dataType": "<string>",
  "columns": [
    "<string>"
  ],
  "logs": "<string>",
  "error": "<string>",
  "aiExplanation": "<string>"
}

Authorizations

​
x-api-key
string
header
required

Optional API key for authentication (enabled via application.yaml)

Body

application/json
​
name
string
required
​
mode
enum<string>
default:test

'run' feeds records into the configured target pipeline; 'test' executes the script and returns results without persisting

Available options:
run,
test
​
params
object

Optional per-run parameters. Each value is stringified and exposed to the tap script as an environment variable (nested objects/arrays are JSON-encoded so the script can json.loads() them back). Use for date-windowed backfills, e.g. {"since": "2026-05-01", "until": "2026-05-02"}. From Airflow, pass Jinja-templated values like {"since": "{{ ds }}"}.

Example:
{
  "since": "2026-05-01",
  "until": "2026-05-02"
}

Response

200 - application/json

Run result

​
tap
string
​
description
string
​
status
enum<string>
Available options:
success,
failure
​
mode
enum<string>

The mode this invocation ran in

Available options:
run,
test
​
targetPipeline
string | null

The pipeline configured on the tap (null if none — records will not persist)

​
persisted
boolean

True iff records were fed into the target pipeline

​
persistedReason
enum<string>

Present when persisted is false; explains why records did not land in a pipeline

Available options:
test_mode,
run_error,
no_records,
no_target_pipeline
​
publisherToken
string

UUID grouping every ingestion job this run submitted. Pass to GET /pipeline/status?publishertoken= to watch load progress. Only present on persisted runs.

​
pipelineTokens
string[]

UUIDs for each StreamNotifier job submitted. Length 1 for structured taps, N for document taps (one per document). Only present on persisted runs.

​
records
object[]
​
recordCount
integer
​
dataType
string
​
columns
string[]
​
logs
string
​
error
string
​
aiExplanation
string