Export CircleCI build history to CSV using a script

Overview

The CircleCI build history export script downloads pipeline history for a single CircleCI project via API v2 and writes it to a CSV file. Use it for reporting, audits, or offline analysis without clicking through the UI.

Each run covers one project. You choose how far back to look (last day, week, custom range, etc.) and whether rows represent pipelines only, workflows, or individual jobs.

Requirements: Python 3.9+, both script files in the same folder (circleci_build_history_export.py and circleci_export_utils.py). No extra packages to install.

Setup

Personal API token — In CircleCI: User Settings → Personal API Tokens. Create a token with access to the project. (Project tokens are not supported.)
Project slug — The identifier from CircleCI URLs:
- GitHub: gh/org/repo
- Bitbucket: bb/workspace/repo
Configure credentials — Copy .env.example to .env and set:
```
 CIRCLE_TOKEN=your-personal-api-token
 CIRCLECI_PROJECT_SLUG=gh/myorg/myrepo
```
The script loads .env automatically. Command-line flags and shell export values override .env.

Basic usage

chmod +x circleci_build_history_export.py   # once

./circleci_build_history_export.py -o builds.csv

With .env configured, that exports the last 7 days (default) to circleci_build_history.csv unless you pass -o.

Specify the project on the command line if needed:

./circleci_build_history_export.py -p gh/myorg/myrepo -o builds.csv

Optional sanity check before a large export:

./circleci_build_history_export.py -p gh/myorg/myrepo --verify-project -o builds.csv

Common options

Option	Purpose
`-p` / `--project`	Project slug (overrides `.env`)
`-o` / `--output`	Output CSV path (default: `circleci_build_history.csv`)
`-i` / `--interval`	`daily`, `weekly` (default), `monthly`, `quarterly`, `yearly`
`--days N`	Last N days (overrides `-i`)
`--since` / `--until`	Fixed UTC window (ISO-8601; overrides `-i` and `--days`)
`--branch NAME`	Limit to one branch
`--mine`	Only pipelines you triggered
`--include-workflows`	One row per workflow (more API calls)
`--include-jobs`	One row per job (most API calls)
`--print-cron`	Print a crontab line for scheduled exports (no token required)
`-q` / `--quiet`	Suppress success message (useful for cron)

Examples

# Last 24 hours
./circleci_build_history_export.py -i daily -o last_day.csv

# Last 14 days
./circleci_build_history_export.py --days 14 -o two_weeks.csv

# Workflows included
./circleci_build_history_export.py -i weekly --include-workflows -o workflows.csv

Output

By default, each CSV row is one pipeline (id, number, state, timestamps, branch, commit, trigger type, errors, etc.).

--include-workflows adds workflow id, name, status, and timestamps.
--include-jobs adds job-level columns as well.

Column names match what the CircleCI API returns for your project.

Scheduling

Cron does not load your login shell, so put secrets in a file you source from crontab (e.g. ~/.circleci-cron.env, mode 600).

Generate a ready-to-paste line:

./circleci_build_history_export.py --print-cron \
  -p gh/myorg/myrepo -i weekly -o /absolute/path/weekly_builds.csv

Use absolute paths for -o and log files. The printed snippet adds --quiet automatically.

Troubleshooting

Symptom	What to check
`Set CIRCLE_TOKEN or pass --token`	Set `CIRCLE_TOKEN` in `.env`, `export`, or pass `--token`
HTTP 401 / 403	Token invalid, expired, or no access to the org/project
HTTP 404	Wrong project slug or project not on this CircleCI account
`No pipelines in the selected time window`	No runs in that period — widen `-i`, `--days`, or `--since` / `--until`
Import error for `circleci_export_utils`	Keep both `.py` files in the same directory

Full flag list: ./circleci_build_history_export.py --help

Additional Resources: