Today we are excited to announce stability of the insights endpoints in CircleCI’s API v2. The newest version of our API offers all the flexibility and intelligence engineering teams want, so you can get even more out of CircleCI. A pipelines-first approach introduces efficiency to your test suite, while our insights endpoints unlock key data around workflows and consumption.
In this post, we’ll outline the endpoints which are now stable for production use.
More data means more informed decisions
The insights endpoints, which have been in preview for several months, allow users to:
- Track status — See which jobs are failing, which workflows have flaky tests, and prioritize efforts for pipeline improvement.
- Monitor duration — Find out which workflows or jobs are taking the longest and identify opportunities where caching, parallelization, and our new convenience images can help speed things up.
- Optimize consumption — Optimize usage on CircleCI with insight into credit spend per job and/or workflow. Predictably plan month over month consumption.
Four new endpoints
With the insights endpoints, users can retrieve aggregate historic data on credit consumption and duration at the workflow and/or job level to build their own dashboards. The endpoints currently return data for a particular workflow within a project and a branch.
View aggregate data at a job and workflow level
GET https://circleci.com/api/v2/insights/{project-slug}/workflows
GET https://circleci.com/api/v2/insights/{project-slug}/workflows/{workflow-name}/jobs
Retrieve aggregate data about project jobs and workflows for a specified branch. The payload contains the following fields:
- Name
- Aggregation window start (UTC)
- Aggregation window end (UTC)
- Successful runs
- Failed runs
- Total runs
- Success rate
- Throughput (average number of runs / day)
- Mean time to recover
- Total credits used
- Duration statistics: max, min, mean, median, p95, standard deviation (all in seconds)
View job and workflow execution data
GET https://circleci.com/api/v2/insights/{project-slug}/workflows/{workflow-name}
GET https://circleci.com/api/v2/insights/{project-slug}/workflows/{workflow-name}/jobs/{job-name}
Retrieve the most recent 250 runs (or runs within the last 90 days, whichever comes first) of a named project workflow for a specified branch. The payload contains the following fields:
- ID
- Status
- Credits used
- Duration (seconds)
- Created at (UTC)
- Stopped at (UTC)
Check out our documentation to learn more.
Improve software delivery with meaningful metrics
Engineering performance is top of mind for a lot of organizations, and successful teams have found that continuous integration is key to delivering results. At CircleCI, we have the distinct privilege of being able to see this evolution firsthand — and have shared these findings in our report The Data-Driven Case for CI.
Our results prove that CI separates high-performers from the rest of the pack. And with this in mind, we are excited to continue delivering tools and intelligence that move teams along their DevOps journey.
By leveraging these insights endpoints, engineering teams can access crucial workflow aggregate information that shows how workflows are performing over a longer duration — empowering organizations to track success/failure rate, throughput, and mean time to recovery, as well as duration metrics. Similarly, workflow run data allows users to track execution times and credits used for a particular workflow. And finally, access to job aggregate information provides an overview of how jobs within a particular workflow are performing over a longer duration—enhancing the ability to measure success rate/failure rate and throughput.
We can’t wait to see how users put this data to use and look forward to continually enhancing intelligence for our customers. If you have any questions or would like to learn more, please check out the related resources below or watch the Improve visibility into your pipelines with CircleCI’s new insights endpoints webinar.
