The DORA metrics API provides the DORA metrics available in Retrospective, Team health insights, and Metrics overview as well as detailed data at the deployment and incident level.
In this article
Permissions
Users calling the DORA metrics API must have the Metrics API permission as well as a valid and unique API key. To enable API permissions for users, you must have the Manage User Permissions permission. Learn more about administrative permissions and API keys in Flow.
Important: If a user does not have both the Metrics API permission and an API key, they can't use the DORA metrics API. If your user can't call the DORA metrics API, verify they have both the permission and a valid API key.
To enable the Metrics API permission for a user, make sure the permission is added to at least one role they are assigned to.
Calling the API
Call the API endpoint over standard HTTPS. Use any tool or programming language that can add the authorization: bearer <API Key> header.
The base URL for the API is https://flow-api.pluralsight.com/dora/build-release.
Supported parameters
There are no required parameters to call the DORA metrics API endpoints. For all endpoints, if no date_range is given, the date range is automatically set to trailing 30 days.
When inputting a date range, it must be in the form: YYYY-MM-DDTmm:hh:ss+tz_offset,YYYY-MM-DDTmm:hh:ss+tz_offset.
Learn more about additional parameters for this API in the Swagger documentation (opens in new tab).
Tip: You can also use the Swagger documentation to receive responses from the API. To do this:
- Click Authorize.
- Put
Bearer <Flow API key>in the value field. Click Authorize. You must includeBearerin the field. - Click Try it out. Input parameters as desired.
- Click Execute.
Endpoints
This API contains seven endpoints to retrieve data from:
- /change: Lists deployments and the commit with the git tag indicating the deployment
- /change/lead_time: Gives the Lead time for changes value and trend for the selected date range
- /deployment: Lists deployments with commit, team, author, and Lead time for changes information
- /deployment/frequency: Gives the Deployment frequency value and trend for the selected date range
- /incident: Lists incidents created in the selected date range
- /incident/change_failure_rate: Gives the Change failure rate value for the selected date range, as well as related, trends, deployments, and incidents
- /incident/time_to_restore: Gives the Time to restore service value for the selected date range, as well as related trends and incidents
/change
Parameters:
| Parameter | Description | Example |
|---|---|---|
| date_range | Specifies the date range to look for deployments in. If no date range is provided, this defaults to trailing 30 days. | date_range=2024-01-01T00:00:00+05:30,2024-01-30T00:00:00+05:30 |
| project_id | Flow-created repo ID. | project_id=1234567 |
| project_id__in | List of Flow-created repo IDs. | project_id__in=[1234567,2345678] |
| project_name | Repo name from Flow. | project_name=example-repo |
| project_tag_id | ID of repo tag from Flow. | project_tag_id=12345 |
| project_tag_id__in | List of repo tags from Flow. | project_tag_id__in=[12345,23456] |
| include_nested_teams | Determines whether data associated with nested teams and team members of the selected team are included in the response. Defaults to true. | include_nested_teams=true |
| team_id | Flow-created team ID. The API response only includes deployments where the apex user of the commit author is a member of the selected team. You can only select one team | team_id=123456 |
| resolution | This field does not affect the response. | |
| deployment_id | Flow-created deployment ID. | deployment_id=123456789 |
| limit | Number of records returned per query. Defaults to 25. The maximum value is 100. | limit=25 |
| offset | Number of records to skip before returning a record. Defaults to 0. | offset=0 |
Example query:
https://flow-api.pluralsight.com/dora/build-release/change/?date_range=2023-01-01,2024-01-01limit=25&offset=0
Example response:
[
{
"id": 1,
"deployment_id": "123456789",
"change": "123456789",
"change_date": "2023-06-12T10:24:13.430Z",
"apex_user_id": 12345678,
"project_id": 1234567,
"lead_time": 3.141
}
]/change/lead_time
| Parameter | Description | Example |
|---|---|---|
| date_range | Specifies the date range to look for deployments in. If no date range is provided, this defaults to trailing 30 days. | date_range=2024-01-01T00:00:00+05:30,2024-01-30T00:00:00+05:30 |
| project_id | Flow-created repo ID. | project_id=1234567 |
| project_id__in | List of Flow-created repo IDs. | project_id__in=[1234567,2345678] |
| project_name | Repo name from Flow. | project_name=example-repo |
| project_tag_id | ID of repo tag from Flow. | project_tag_id=12345 |
| project_tag_id__in | List of repo tags from Flow. | project_tag_id__in=[12345,23456] |
| include_nested_teams | Determines whether data associated with nested teams and team members of a selected team are included in the response. Defaults to true. | include_nested_teams=true |
| team_id | Flow team ID. Only deployments where the apex user of a commit author is a member of the selected team are included. Only a single team can be selected. | team_id=123456 |
| resolution | Determines on what basis the metric calculation should be done on a given timeframe. Options are year, quarter, month, week, day, and period, where period is the default. | resolution=period |
| deployment_id | Flow deployment ID. | deployment_id=123456789 |
Example query:
https://flow-api.pluralsight.com/dora/build-release/change/lead_time/?date_range=2023-01-01,2024-01-01limit=25&offset=0
Example response:
{
"median": 1146509.5,
"trend": -13.21,
"performance": "medium",
"timeseries": []
}/deployment
Parameters:
| Parameter | Description | Example |
|---|---|---|
| ordering |
Determines the field used while ordering the results. Options are id, deployment_time, deployment_name, author_name, author_ids, team_ids, and team_name where id is the default. |
ordering=id |
| date_range | Specifies the date range to look for deployments in. If no date range is provided, this defaults to trailing 30 days. | date_range=2024-01-01T00:00:00+05:30,2024-01-30T00:00:00+05:30 |
| project_id | Flow-created repo ID. | project_id=1234567 |
| project_id__in | List of Flow-created repo IDs. | project_id__in=[1234567,2345678] |
| project_name | Repo name from Flow. | project_name=example-repo |
| project_tag_id | ID of repo tag from Flow. | project_tag_id=12345 |
| project_tag_id__in | List of repo tags from Flow. | project_tag_id__in=[12345,23456] |
| include_nested_teams | Determines whether data associated with nested teams and team members of the selected team are included in the response. Defaults to true. | include_nested_teams=true |
| team_id | Flow-created team ID. The API response only includes deployments where the apex user of the commit author is a member of the selected team. You can only select one team | team_id=123456 |
| resolution | This field does not affect the response. | |
| limit | Number of records returned per query. Defaults to 25. The maximum value is 100. | limit=25 |
| offset | Number of records to skip before returning a record. Defaults to 0. | offset=0 |
Example query:
https://flow-api.pluralsight.com/dora/build-release/deployment/?date_range=2023-01-01,2024-01-01limit=25&offset=0
Example response:
[
{
"id": 123456789,
"project": 123456,
"deployment_time": "2024-05-15T13:15:04Z",
"source": "GIT_TAG",
"project_name": "example-repo",
"project_link": "https://github.com/example-organization/example-repo.git",
"deployment_name": [
"Example deployment"
],
"lead_time": 1268878,
"first_commit_date": "2024-04-08T20:08:07Z",
"commit_count": 131,
"team_ids": [
123456,
234567,
],
"team_name": [
"Frontend team",
"Engineering",
],
"author_ids": [
1234567,
2345678,
],
"author_name": [
"Stephanie Ventura",
"Steve Walsh",
]
},
{
"id": 234567890,
"project": 2345678,
"deployment_time": "2024-05-15T22:27:23Z",
"source": "GIT_TAG",
"project_name": "example-credentials-manager",
"project_link": "https://github.com/dev-organization/example-credentials-manager.git",
"deployment_name": [
"release-candidate-30"
],
"lead_time": 182842,
"first_commit_date": "2024-05-09T15:32:18Z",
"commit_count": 25,
"team_ids": [
987654,
],
"team_name": [
"Data Platform",
],
"author_ids": [
1357924
],
"author_name": [
"Jamie Flores"
]
}
]/deployment/frequency
Parameters:
| Parameter | Description | Example |
|---|---|---|
| ordering | Determines the field used while ordering the results. Options are id, deployment_time, where id is the default. | |
| date_range | Specifies the date range to look for deployments in. If no date range is provided, this defaults to trailing 30 days. | date_range=2024-01-01T00:00:00+05:30,2024-01-30T00:00:00+05:30 |
| project_id | Flow-created repo ID. | project_id=1234567 |
| project_id__in | List of Flow-created repo IDs. | project_id__in=[1234567,2345678] |
| project_name | Repo name from Flow. | project_name=example-repo |
| project_tag_id | ID of repo tag from Flow. | project_tag_id=12345 |
| project_tag_id__in | List of repo tags from Flow. | project_tag_id__in=[12345,23456] |
| include_nested_teams | Determines whether data associated with nested teams and team members of the selected team are included in the response. Defaults to true. | include_nested_teams=true |
| team_id | Flow-created team ID. The API response only includes deployments where the apex user of the commit author is a member of the selected team. You can only select one team. | team_id=123456 |
| resolution | Determines on what basis the metric calculation should be done on a given timeframe. Options are year, quarter, month, week, day, period, where period is the default. | resolution=day |
Example query:
https://flow-api.pluralsight.com/dora/build-release/deployment/frequency/?date_range=2023-01-01,2024-01-01limit=25&offset=0
Example response
{
"weekly_median": 5,
"performance": "elite",
"total": 68,
"trend": -6.93,
"frequency": "daily",
"timeseries": []
}/incident
| Parameter | Description | Example |
|---|---|---|
| ordering | Determines the response field to use when ordering results. “id” is the default value. | ordering=id |
| date_range | Specifies the date range to look for incidents in. If no date range is provided, defaults to trailing 30 days. | date_range=2024-01-01T00:00:00+05:30,2024-01-30T00:00:00+05:30 |
| project_id | Flow-created repo ID. | project_id=1234567 |
| project_id__in | List of Flow-created repo IDs. | project_id__in=[1234567,2345678] |
| project_name | Repo name from Flow. | project_name=example-repo |
| project_tag_id | ID of repo tag from Flow. | project_tag_id=12345 |
| project_tag_id__in | List of repo tags from Flow. | project_tag_id__in=[12345,23456] |
| include_nested_teams | Determines whether data associated with nested teams and team members of a selected team are included in the response. Defaults to true. | include_nested_teams=true |
| team_id | Flow team ID. Only deployments where the apex user associated with an assignee on the incident is a member of the selected team. Only a single team can be selected. | team_id=123456 |
| resolution | This field does not affect the response. | |
| deployment_id | Flow deployment ID. | deployment_id=123456789 |
| limit | Number of records returned per query. Defaults to 25. Maximum is 100. | limit=25 |
| offset | Number of records to skip before returning a record. Defaults to 0. | offset=0 |
Example query:
https://flow-api.pluralsight.com/dora/build-release/incident/?date_range=2023-01-01,2024-01-01limit=25&offset=0
Example response:
[
{
"icon_url": "https://incident-location.net/image",
"ticket_number": "EX-1234",
"incident_link": "https://incident-location.net/browse/EX-1234",
"title": "Credentials manager incident",
"external_id": 12345678,
"incident_date": "2023-11-16T00:53:51.170000Z",
"resolution_date": "2023-12-06T20:52:05.470000Z",
"time_to_restore": 1799894.3
},
{
"icon_url": "https://incident-location.net/image2",
"ticket_number": "EX-1235",
"incident_link": "https://incident-location.net/browse/EX-1235",
"title": "Missing data in customer organization",
"external_id": 23456789,
"incident_date": "2023-10-30T20:05:33.782000Z",
"resolution_date": "2023-11-29T22:40:15.123000Z",
"time_to_restore": 2601281.341
}
]/incident/change_failure_rate
Parameters:
| Parameter | Description | Example |
|---|---|---|
| ordering | Determines the field used while ordering the results. id is the default value. | ordering=id |
| date_range | Specifies the date range to look for deployments and incidents in. If no date range is provided, defaults to trailing 30 days. | date_range=2024-01-01T00:00:00+05:30,2024-01-30T00:00:00+05:30 |
| project_id | Flow-created repo ID. | project_id=1234567 |
| project_id__in | List of Flow-created repo IDs. | project_id__in=[1234567,2345678] |
| project_name | Repo name from Flow. | project_name=example-repo |
| project_tag_id | ID of repo tag from Flow. | project_tag_id=12345 |
| project_tag_id__in | List of repo tags from Flow. | project_tag_id__in=[12345,23456] |
| include_nested_teams | Determines whether data associated with nested teams and team members of a selected team are included in the response. Defaults to true. | include_nested_teams=true |
| team_id | Flow team ID. Only includes deployments where the apex user of the commit author is a member of the selected team and incidents where one of the assignees is an apex user on the selected team. Only a single team can be selected. | team_id=123456 |
| resolution | Determines on what basis the metric calculation should be done on a given timeframe. Options are year, quarter, month, week, day, period, where period is the default. | resolution=day |
| deployment_id | Flow deployment ID. | deployment_id=12345678 |
Example query:
https://flow-api.pluralsight.com/dora/build-release/incident/change_failure_rate/?date_range=2023-01-01,2024-01-01limit=25&offset=0
Example response:
{
"overall_failure_rate": 0.8008281904610115,
"timeseries": [
{
"end_date": "2000-01-23",
"failure_rate": 5.637376656633329,
"deployments": 7,
"performance": "low",
"failures": 2,
"incident_link": "https://example-incident-link.com",
"deployment_link": "https://example-deployment-link.com",
"start_date": "2000-01-23"
},
{
"end_date": "2000-01-23",
"failure_rate": 5.637376656633329,
"deployments": 7,
"performance": "low",
"failures": 2,
"incident_link": "https://example-incident-link.com",
"deployment_link": "https://example-deployment-link.com",
"start_date": "2000-01-23"
}
],
"incidents": [
{
"external_id": 12345,
"incident_date": "2022-04-15T00:00:00Z",
"resolution_date": "2022-04-20T00:00:00Z",
"time_to_restore": 300,
"icon_url": "https://incident-location.net/image",
"incident_link": "https://incident-location.net/browse/EX-3456",
"ticket_number": "EX-3456",
"title": "Title of the ticket"
}
],
"trend": 6.027456183070403,
"number_of_failures": 1,
"overall_performance": "low",
"total_deployments": 5
}/incident/time_to_restore
Parameters:
| Parameter | Description | Example |
|---|---|---|
| ordering | Determines the field used when ordering the results. id is the default value. | ordering=id |
| date_range | Specifies the date range to look for incidents in. If no date range is provided, defaults to trailing 30 days. | date_range=2024-01-01T00:00:00+05:30,2024-01-30T00:00:00+05:30 |
| project_id | Flow-created repo ID. | project_id=1234567 |
| project_id__in | List of Flow-created repo IDs. | project_id__in=[1234567,2345678] |
| project_name | Repo name from Flow. | project_name=example-repo |
| project_tag_id | ID of repo tag from Flow. | project_tag_id=12345 |
| project_tag_id__in | List of repo tags from Flow. | project_tag_id__in=[12345,23456] |
| include_nested_teams | Determines whether data associated with nested teams and team members of a selected team are included in the response. Defaults to true. | include_nested_teams=true |
| team_id | Flow team ID. Only deployments where the apex user of an assignee on the incident is a member of the selected team. Only a single team can be selected. | team_id=123456 |
| resolution | Determines on what basis the metric calculation should be done on a given timeframe. Options are year, quarter, month, week, day, period, where period is the default. | resolution=day |
| deployment_id | Flow deployment ID. | deployment_id=123456789 |
Example query
https://flow-api.pluralsight.com/dora/build-release/incident/time_to_restore/?date_range=2023-01-01,2024-01-01limit=25&offset=0
Example response
{
"time_to_restore": 4578704.184266667,
"trend": -1.24,
"performance": "low",
"timeseries": [],
"incidents": [
{
"icon_url": "https://incident-location.net/image",
"ticket_number": "EX-2345",
"incident_link": "https://incident-location.net/browse/EX-2345",
"title": "Missing data",
"external_id": 123456789,
"incident_date": "2024-04-01T07:39:58.986000Z",
"resolution_date": "2024-05-28T20:05:54.933000Z",
"time_to_restore": 4969555.947
},
{
"icon_url": "https://incident-location.net/image2",
"ticket_number": "EX-2346",
"incident_link": "https://incident-location.net/browse/EX-2346",
"title": "Delete old project",
"external_id": 234567890,
"incident_date": "2024-05-17T17:17:15.468000Z",
"resolution_date": "2024-05-28T18:15:07.277000Z",
"time_to_restore": 953871.809
}
]
}