DORA metrics API

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.

On this page: 1 Permissions 2 Calling the API 3 Supported parameters 4 Endpoints 4.1 /change 4.2 /change/lead_time 4.3 /deployment 4.4 /deployment/frequency 4.5 /incident 4.6 /incident/change_failure_rate 4.7 /incident/time_to_restore

On this page: 1 Permissions 2 Calling the API 3 Supported parameters 4 Endpoints 4.1 /change 4.2 /change/lead_time 4.3 /deployment 4.4 /deployment/frequency 4.5 /incident 4.6 /incident/change_failure_rate 4.7 /incident/time_to_restore

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.

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).

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 include Bearer in 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

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

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

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

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

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

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

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
    }
  ]

  }