pipelineRuns.upsert

Insert or update a pipeline workflow run.

Facts


Method	`POST https://yourinstance.getdx.net/api/pipelineRuns.upsert`

Arguments

Required arguments

Name	Type	Description
`token`	`Token`	Auth token passed as an HTTP header.
`pipeline_name`	`Text`	Name of the pipeline that this job is for. Example: `integration_tests`
`pipeline_source`	`Text`	Which project source is this? CircleCI, Jenkins, Tekton etc. Example: `Tekton`
`reference_id`	`Text`	A globally unique identifier for this run. Example: `AA713E04-1880-4E17-8C49-4A41733DAFCF`
`started_at`	`ISO-8601`	Note that each request does not need to have the same started_at value. They can arrive in any sequence and the earliest value will be used. Example: `2025-01-01T12:05:00`

Optional arguments

Name	Type	Description
`status`	`Text`	`failure`, `running`, `success`, or `cancelled`
`finished_at`	`ISO-8601`	Timestamp for when the pipeline run finished. Example: `2025-01-01T12:10:00`
`repository`	`Text`	The full name of the repository. Example: `getdx/some_repo`
`commit_sha`	`Text`	The commit SHA that the build was run on. If commit SHA is provided, repository is required.
`pr_number`	`Integer`	The number of the pull request that the build was run on. If PR number is provided, repository is required. Example: `1`
`source_url`	`Text`	The web address to view details about the pipeline run.
`head_branch`	`Text`	Used to know which branch the pipeline run was run against. Example: `main`
`email`	`Text`	Email address of the user who initiated the build. Example: `john@getdx.com`
`github_username`	`Text`	GitHub username of the user who initiated the build. Example: `johndoe`
`gitlab_username`	`Text`	GitLab username of the user who initiated the build. Example: `johndoe`

Usage info

This API method provides a flexible way to capture CI data in DX where a native data connector does not exist.

To use this API method, instrument your pipelines to send requests to our endpoint with updates on the status of builds. These requests are summed up to create a database record that includes the duration, user attribution, and associated code change.

For example, given the following sequence of API requests:

Name	Identifier	Started	Finished	Status
test_run	step 1	11:25:18		running
test_run	step 2	11:25:21		success
test_run	step 3	11:24:40		failure
test_run	step 4	11:25:21		running
test_run	step 5	11:26:07	11:46:67	success

DX will collect them into one pipeline workflow run record like this:

The final status will be calculated by looking at the notifications sorted by started_at and replacing the status if the newer status is higher on this priority list than the previous status:

failure > cancelled > success > running > unknown

By default the status will be unknown if the DX API is notified about a run without any other status provided. This might happen if you have a pre-boot startup process that informs us about the run before any steps or tasks have been run.

In addition to collecting the overall result of a run in one place, DX also links the run to to code changes, and attributes it to individuals and teams when an identifier (i.e., email, GitHub username, or GitLab username) is included in request data.

Example request

This is a typical request:

curl -X POST https://yourinstance.getdx.net/api/pipelineRuns.upsert \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
  -d '{
  "pipeline_name": "build_panda_finder",
  "pipeline_source": "Tekton",
  "reference_id": "AA713E04-1880-4E17-8C49-4A41733DAFCF",
  "started_at": "2025-01-01T12:05:00",
  "finished_at": "2025-01-01T12:10:00",
  "status": "success"
  }'

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok param in the response.

Error Code	Description
`not_authed`	This error occurs if the API request does not include a valid API key for authentication.
`invalid_auth`	The provided API key is invalid. This can happen if the key is expired or does not exist.
`invalid_json`	The JSON body of the request could not be parsed. This usually indicates a syntax error.
`invalid_timestamp`	The `started_at` or `finished_at` format was not a readable ISO-8601 date format.
`required_params_missing`	One or more required parameters were not provided in the request.