CircleCI Insights API
Endpoints for retrieving workflow and job metrics, summary data, and test performance insights.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/circleci-insights-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: CircleCI REST API v2 Insights API
description: The CircleCI REST API v2 provides programmatic access to CircleCI services for managing pipelines, projects, workflows, jobs, and users. Developers can trigger pipelines, retrieve build status, manage contexts and environment variables, and access usage reports. The API uses token-based authentication via a Circle-Token header and returns JSON responses. It supports operations for project configuration, workflow management, artifact retrieval, and insights into build performance.
version: '2.0'
contact:
name: CircleCI Support
url: https://support.circleci.com
termsOfService: https://circleci.com/terms-of-service/
license:
name: MIT
url: https://opensource.org/licenses/MIT
servers:
- url: https://circleci.com/api/v2
description: CircleCI Production API
security:
- apiToken: []
tags:
- name: Insights
description: Endpoints for retrieving workflow and job metrics, summary data, and test performance insights.
paths:
/insights/{project-slug}/workflows:
get:
operationId: getProjectWorkflowMetrics
summary: Get project workflow metrics
description: Returns summary metrics for the workflows of a given project, including success rates, duration metrics, and throughput.
tags:
- Insights
parameters:
- $ref: '#/components/parameters/ProjectSlugParam'
- name: branch
in: query
description: Filter by branch name
schema:
type: string
- name: reporting-window
in: query
description: The time window for metrics
schema:
type: string
enum:
- last-7-days
- last-30-days
- last-60-days
- last-90-days
- $ref: '#/components/parameters/PageTokenParam'
responses:
'200':
description: Successfully retrieved workflow metrics
content:
application/json:
schema:
$ref: '#/components/schemas/InsightsWorkflowMetrics'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/insights/{project-slug}/workflows/{workflow-name}:
get:
operationId: getWorkflowRuns
summary: Get recent runs of a workflow
description: Returns recent runs of a named workflow, containing status, duration, and credits consumed.
tags:
- Insights
parameters:
- $ref: '#/components/parameters/ProjectSlugParam'
- name: workflow-name
in: path
required: true
description: The name of the workflow
schema:
type: string
- name: branch
in: query
description: Filter by branch name
schema:
type: string
- $ref: '#/components/parameters/PageTokenParam'
responses:
'200':
description: Successfully retrieved workflow runs
content:
application/json:
schema:
$ref: '#/components/schemas/InsightsWorkflowRuns'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/insights/{project-slug}/workflows/{workflow-name}/jobs:
get:
operationId: getWorkflowJobMetrics
summary: Get workflow job metrics
description: Returns summary metrics for the jobs within a named workflow, including success rates and duration metrics.
tags:
- Insights
parameters:
- $ref: '#/components/parameters/ProjectSlugParam'
- name: workflow-name
in: path
required: true
description: The name of the workflow
schema:
type: string
- name: branch
in: query
description: Filter by branch name
schema:
type: string
- name: reporting-window
in: query
description: The time window for metrics
schema:
type: string
enum:
- last-7-days
- last-30-days
- last-60-days
- last-90-days
- $ref: '#/components/parameters/PageTokenParam'
responses:
'200':
description: Successfully retrieved job metrics
content:
application/json:
schema:
$ref: '#/components/schemas/InsightsJobMetrics'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/insights/{project-slug}/workflows/{workflow-name}/test-metrics:
get:
operationId: getWorkflowTestMetrics
summary: Get test metrics for a workflow
description: Returns test metrics for a named workflow, including most frequently failing tests and slowest tests.
tags:
- Insights
parameters:
- $ref: '#/components/parameters/ProjectSlugParam'
- name: workflow-name
in: path
required: true
description: The name of the workflow
schema:
type: string
responses:
'200':
description: Successfully retrieved test metrics
content:
application/json:
schema:
$ref: '#/components/schemas/InsightsTestMetrics'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
InsightsWorkflowRuns:
type: object
properties:
items:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
description: The workflow run ID
status:
type: string
description: The status of the run
duration:
type: integer
description: Duration in seconds
created_at:
type: string
format: date-time
description: When the run was created
stopped_at:
type: string
format: date-time
description: When the run stopped
credits_used:
type: integer
description: Credits consumed by this run
branch:
type: string
description: The branch that was built
description: List of workflow runs
next_page_token:
type: string
description: Token for retrieving the next page
InsightsTestMetrics:
type: object
properties:
average_test_count:
type: integer
description: Average number of tests per run
most_failed_tests:
type: array
items:
type: object
properties:
test_name:
type: string
description: Name of the test
classname:
type: string
description: Class name of the test
failed_runs:
type: integer
description: Number of failed runs
total_runs:
type: integer
description: Total runs of this test
description: Most frequently failing tests
slowest_tests:
type: array
items:
type: object
properties:
test_name:
type: string
description: Name of the test
classname:
type: string
description: Class name of the test
p95_duration:
type: number
format: float
description: 95th percentile duration
description: Slowest tests by duration
test_runs:
type: array
items:
type: object
properties:
pipeline_number:
type: integer
description: The pipeline number
workflow_id:
type: string
format: uuid
description: The workflow ID
success_rate:
type: number
format: float
description: Success rate of tests in this run
test_counts:
type: object
properties:
error:
type: integer
description: Number of errored tests
failure:
type: integer
description: Number of failed tests
success:
type: integer
description: Number of successful tests
skipped:
type: integer
description: Number of skipped tests
description: Test counts by result
description: Recent test run summaries
InsightsWorkflowMetrics:
type: object
properties:
items:
type: array
items:
type: object
properties:
name:
type: string
description: The workflow name
metrics:
type: object
properties:
total_runs:
type: integer
description: Total number of runs
successful_runs:
type: integer
description: Number of successful runs
failed_runs:
type: integer
description: Number of failed runs
success_rate:
type: number
format: float
description: Success rate as a decimal
duration_metrics:
type: object
properties:
min:
type: integer
description: Minimum duration in seconds
mean:
type: integer
description: Mean duration in seconds
median:
type: integer
description: Median duration in seconds
p95:
type: integer
description: 95th percentile duration
max:
type: integer
description: Maximum duration in seconds
description: Duration statistics
total_credits_used:
type: integer
description: Total credits consumed
description: Workflow metrics
window_start:
type: string
format: date-time
description: Start of the reporting window
window_end:
type: string
format: date-time
description: End of the reporting window
description: List of workflow metric summaries
next_page_token:
type: string
description: Token for retrieving the next page
ErrorResponse:
type: object
properties:
message:
type: string
description: A human-readable error message
InsightsJobMetrics:
type: object
properties:
items:
type: array
items:
type: object
properties:
name:
type: string
description: The job name
metrics:
type: object
properties:
total_runs:
type: integer
description: Total number of runs
successful_runs:
type: integer
description: Number of successful runs
failed_runs:
type: integer
description: Number of failed runs
success_rate:
type: number
format: float
description: Success rate as a decimal
duration_metrics:
type: object
properties:
min:
type: integer
description: Minimum duration
mean:
type: integer
description: Mean duration
median:
type: integer
description: Median duration
p95:
type: integer
description: 95th percentile duration
max:
type: integer
description: Maximum duration
description: Duration statistics
total_credits_used:
type: integer
description: Total credits consumed
description: Job metrics
description: List of job metric summaries
next_page_token:
type: string
description: Token for retrieving the next page
parameters:
ProjectSlugParam:
name: project-slug
in: path
required: true
description: The project slug in the form vcs-slug/org-name/repo-name (e.g., gh/CircleCI-Public/api-preview-docs)
schema:
type: string
PageTokenParam:
name: page-token
in: query
description: Token for retrieving the next page of results
schema:
type: string
securitySchemes:
apiToken:
type: apiKey
in: header
name: Circle-Token
description: Personal API token for authenticating with the CircleCI API. Generate tokens in your CircleCI account settings.
basicAuth:
type: http
scheme: basic
description: HTTP basic authentication using a personal API token as the username with an empty password.
externalDocs:
description: CircleCI API v2 Documentation
url: https://circleci.com/docs/api/v2/