CircleCI

CircleCI Insights API

Endpoints for retrieving workflow and job metrics, summary data, and test performance insights.

GitHub OpenAPI
Business capability
Engineering Productivity Management BC-4200.70

Operations 4

GET /insights/{project-slug}/workflows Get project workflow metrics #
GET /insights/{project-slug}/workflows/{workflow-name} Get recent runs of a workflow #
GET /insights/{project-slug}/workflows/{workflow-name}/jobs Get workflow job metrics #
GET /insights/{project-slug}/workflows/{workflow-name}/test-metrics Get test metrics for a workflow #

Documentation

📖
Documentation
https://circleci.com/docs/api/v2/
📖
Documentation
https://circleci.com/docs/api/v1/

Specifications

⚙
OpenAPI
https://artifacts.apis.io/circleci/openapi/circleci-insights-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/circleci/json-schema/circleci-insights-test-metrics-schema.json
📊
JSONSchema
https://artifacts.apis.io/circleci/json-schema/circleci-insights-workflow-metrics-schema.json
📊
JSONSchema
https://artifacts.apis.io/circleci/json-schema/circleci-insights-job-metrics-schema.json
📊
JSONSchema
https://artifacts.apis.io/circleci/json-schema/circleci-insights-workflow-runs-schema.json

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.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/circleci:circleci-insights-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

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.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

circleci-insights-api-openapi.yml Raw ↑ 
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:
    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
    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
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: A human-readable error message
    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
    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
  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/