Overview

The Current Concurrency Snapshot script provides a real-time view of your CircleCI organization's resource usage and concurrency across different resource classes.

Important Notes

This script provides a snapshot of the current moment—it doesn't show historical trends
This should not be used regularly, and only when trouble shooting
Results reflect only running jobs at the time of execution
Requires appropriate API token permissions to access organization data
May not support use with standalone organizations
For CircleCI Cloud customers only (not for Server installations)
This script was made to assist customers but is NOT a maintained and supported CircleCI product offering. Use at your own discretion.

What It Does

This script queries the CircleCI API to show:

Currently running jobs across all projects in your organization
Which resource classes are being used
How many jobs are running on each resource class
Concurrency usage against your plan limits

This snapshot helps you understand your resource utilization at a specific point in time, which is useful for:

Identifying resource bottlenecks
Planning capacity upgrades
Troubleshooting performance issues
Understanding which resource classes are most utilized

Prerequisites

Python 3.6 or higher
A CircleCI personal API token (generate one here)
Your organization ID or VCS organization name

Example Output:

Organization: gh/org-name
Pipelines scanned: 50 (with active workflows: 2)

Current concurrency usage (all executors):
  Running jobs:  2
  Queued jobs:  0
  Total in use: 2

To Explain:

"Running" is the count of jobs that the API reports as having a "running" status.

"Queued" is the count of jobs that are "queued", "blocked" or "pending" status.

"Total in use" is the total number of jobs that contribute towards concurrency usage.

Installation/Usage

Please read the README in its entirety and follow the instructions found there before using this script

Potential Use Cases

Troubleshooting Queue Times

If jobs are queuing, run this script to see if you're hitting concurrency limits on specific resource classes. This will tell you that there is not an issue with CircleCI itself, but with usage limits.

Capacity Planning

Run the script during peak usage times to understand your typical resource requirements and plan upgrades accordingly.

Cost Optimization

Identify which resource classes are heavily used versus underutilized to optimize your resource class selection.

Before Contacting Support

When opening a support ticket about performance or concurrency issues, include the output from this script to provide immediate context about your current usage if you believe there is an issue.

Troubleshooting

"Invalid API token" error:

Verify your token is correct and hasn't expired
Ensure the token has appropriate permissions to view organization data

"Organization not found" error:

Check your org-slug format (should be vcs-type/org-name)
Verify you have access to the specified organization

No jobs showing despite active builds:

The script only captures jobs running at that exact moment
Try running it again during a busier time

Additional Resources

Using the Current Concurrency Snapshot Script