api.md

description
Integrate with Trunk CI Analytics using the API

CI Analytics

The Trunk CI Analytics API provides access to instrument any CI or build system. The API is an HTTP REST API, returns JSON from all requests, and uses standard HTTP response codes.

All requests must be authenticated by providing the x-api-token header.

Track Events

POST https://api.trunk.io/v1/metrics/trackEvents

Track Events

POST https://api.trunk.io/v1/metrics/trackEvents

The track events endpoint uploads event data about a CI run. Each event contains a start and end timestamp, metrics, tags, and an optional parent association ID.

Headers

Name	Type	Description
Content-Type*	String	application/json
x-api-token*	String	Trunk API Token
x-source	String	Name of the uploading client

Request Body

Name	Type	Description
repo*	Object	The repository in which the CI Event ran. See repo schema.
events*	Array	An array of event objects. See event schema.

{% tabs %} {% tab title="200: OK Events were created successfully" %}

{% endtab %}

{% tab title="401: Unauthorized Request is not authorized" %}

{% endtab %}

{% tab title="400: Bad Request Request body is not formed correctly" %}

{% endtab %} {% endtabs %}

Headers

Name	Type	Description
Content-Type*	String	AO8NCa6G0paE
x-api-token*	String	3HCw9xVi1CBh
x-source	String	JBoUSZxipIYA

Request Body

Name	Type	Description
repo*	Object	eN1mmETFshzM
events*	Array	Mk0uImz3AIoq

Repo

Repo object properties:

Property	Description	Required
host	The name of the code host for this repository. Currently only github.com is supported.	Required
owner	The owner of this repository	Required
name	The name of this repository	Required

For example, the repository https://github.com/trunk-io/jenkins-plugin would be

{
  "host": "github.com",
  "owner": "trunk-io",
  "name": "jenkins-plugin"
}

Event

Event object properties

Property	Description	Required	Type
id	A unique identifier for this event	Required	String
chainId	The root event id. chainId is used to group all events that were part of the same run.	Required	String
parent	The parent event. Not required if this event has no parent.	Optional	Object
createdAt	The millisecond epoch marking the start of this event	Required	Number
finishedAt	The millisecond epoch marking the end of this event	Optional	Number
conclusion	"SUCCESS" | "FAILURE" | "CANCELLED" | "TIMED_OUT" | "SKIPPED"	Optional	String
payload	An object containing metrics and tags. See payload schema.	Optional	Object
sequence	Describes the workflow, pipeline, or job, etc. that this event is from. See sequence schema.	Optional	Object

Parent

Parent object properties:

Property	Description	Required	Type
eventId	The parent event's unique identifier	Required	String
sequenceKey	The key to the parent event's sequence	Required	String

Payload

Payload object properties:

Property	Description	Required	Type
metrics	Each metric is an object containing the metric key and value (where value is a number). For example: {"k": "duration_ms", "v": 101920}	Required	Object
tags	Each metric is an object containing the tag key and value (where value can be a number or a string). For example: {"k": "runner", "v": "self-hosted"}	Required	Object

Sequence

A sequence describes the CI pipeline, job, workflow, etc. Events are grouped under sequences using the sequenceKey.

Sequence object properties:

Property	Description	Required	Type	Examples
platform	The string name of the CI platform. Must be snake_case.	Required	String	jenkins, trunk_merge.
kind	The type of the sequence.	Required	String	job, workflow
key	An identifier for this sequence. Must be unique within the repo and < 128 characters.	Required	String	my-global-uuid
name	The name of this sequence. These will appear as top-level entries in your CI Analytics dashboards.	Required	String	Integration Tests [linux].
payload	The tags for this sequence. See payload schema. (note: metrics are not supported for a sequence)	Required	Object	{ metrics: [], tags: [] }

Example Request

{% code fullWidth="true" %}

curl \
    -i \
    -X POST https://api.trunk.io/v1/metrics/trackEvents \
    -H "Content-Type: application/json" \
-H "x-source: curl-sample" \
    -H "x-api-token: {REDACTED}" \
    -d '{
	"repo": {
		"host": "github.com",
		"owner": "trunk-io",
		"name": "jenkins-plugin"
	},
	"events": [{
			"id": "fba555ee-90ce-42ca-a60c-38d200e9290e",
			"chainId": "b0ea8b0d-6574-4421-a63b-56f04eab9738",
			"createdAt": 1694616487000,
			"finishedAt": 1694615487000,
			"conclusion": "SUCCESS",
			"sequence": {
				"platform": "Jenkins",
				"kind": "pipeline",
				"key": "test-pipeline",
				"name": "Trying out a test pipeline",
				"payload": {
					"tags": [{
						"k": "label",
						"v": "self-hosted"
					}]
				}
			},
			"payload": {
				"metrics": [{
						"k": "duration_ms",
						"v": 1000
					},
					{
						"k": "api_latency",
						"v": 500
					}
				],
				"tags": [{
						"k": "branch",
						"v": "merge-PR-1"
					},
					{
						"k": "sha",
						"v": "88962a71bcfa92e5950670fc7e3f2b9f8d993b87"
					}
				]
			}
		},
		{
			"id": "test-workflow-a-1",
			"chainId": "test-workflow-a-1",
			"createdAt": 1694616487000,
			"finishedAt": 1694615487000,
			"conclusion": "SUCCESS",
			"parent": {
				"eventId": "fba555ee-90ce-42ca-a60c-38d200e9290e",
				"chainId": "b0ea8b0d-6574-4421-a63b-56f04eab9738"
			},
			"sequence": {
				"platform": "Jenkins",
				"kind": "nested-pipeline",
				"key": "test-pipeline/nested-pipeline",
				"name": "Trying out a test nested pipeline",
				"payload": {
					"tags": [{
						"k": "label",
						"v": "self-hosted"
					}]
				}
			},
			"payload": {
				"metrics": [{
						"k": "duration_ms",
						"v": 1000
					},
					{
						"k": "api_latency",
						"v": 500
					}
				],
				"tags": [{
						"k": "branch",
						"v": "merge-PR-1"
					},
					{
						"k": "sha",
						"v": "88962a71bcfa92e5950670fc7e3f2b9f8d993b87"
					}
				]
			}
		}
	]
}'

{% endcode %}