How to Get Information About Flaky and Slowest Tests via the Insights API

Introduction

When you need to manually analyze test result data, you can use the CircleCI API's test metadata endpoint to retrieve raw test data from your builds. This allows you to identify flaky tests and determine which tests take the longest to complete.

Prerequisites

Before making API requests, you need:

A personal API token (create one in your CircleCI user settings)
Your project slug (format: {vcs-type}/{org-name}/{project-name})
The job number you want to analyze

Instructions

Step 1: Store Your API Token

Store your personal API token as an environment variable:

export CIRCLE_TOKEN="your_token_here"

Step 2: Make the API Request

Use the following curl command to retrieve test metadata:

  curl --request GET \ 
  --url https://circleci.com/api/v2/project/{project-slug}/{job-number}/tests \ 
  --header "Circle-Token: $CIRCLE_TOKEN"

Replace {project-slug} with your project information and {job-number} with the specific job number.

Step 3: Review the Response

A successful request returns test metadata in JSON format:

 
  { "items": [ 
    { "message": "", 
      "source": "", 
      "run_time": "", 
      "file": "", 
      "result": "", 
      "name": "", 
      "classname": "" 
    } 
  ], 
  "next_page_token": "string" 
  }

Outcome

By collecting this data across multiple jobs, you can identify patterns that reveal flaky tests (tests with inconsistent results) and slow tests (tests with long run times).

Additional Resources

CircleCI API v2 Documentation - Complete API reference
API Developers Guide - Getting started with the CircleCI API
Collecting Test Data - How to configure test result collection