Linear Issues Export Script

This Python script retrieves all issues closed in the last 12 months from the Linear API and exports them to a CSV file for audit evidence.

Developed by 24Slides | License: MIT

Features

• Authentication: Uses LINEAR_API_KEY environment variable (API key format, not Bearer token)
• Date Filtering: Calculates date exactly 12 months ago (365 days) and filters issues completed after that date
• Status Filtering: Only retrieves issues with state type "completed" or "canceled"
• Pagination: Handles multiple pages of results automatically using Linear's GraphQL pagination
• Rate Limiting: Automatically handles API rate limits with exponential backoff retry (up to 5 attempts)
• Network Resilience: Retries on timeouts and connection errors
• Complete Data: Exports identifier, title, completedAt, creator name, assignee name, URL, and team name
• CSV Output: Saves results to linear_closed_issues_last_12mo.csv

Requirements

• Python 3.6 or higher
• Linear API key with read access to issues

Installation

1. Clone or download this repository

2. Install dependencies:

   pip install -r requirements.txt

Configuration

Get Your Linear API Key

1. Go to Linear Settings → API
2. Create a new Personal API Key
3. Copy the key (it starts with lin_api_...)

Set the Environment Variable

Option 1: Using .env file (Recommended)

1. Copy the template file:

   cp env.template .env

2. Edit .env and replace your-api-key-here with your actual API key:

   LINEAR_API_KEY=lin_api_xxxxxxxxxxxxxx

The script will automatically load the .env file when you run it.

Option 2: Set environment variable directly

On macOS/Linux:

export LINEAR_API_KEY='your-api-key-here'

On Windows (PowerShell):

$env:LINEAR_API_KEY='your-api-key-here'

On Windows (Command Prompt):

set LINEAR_API_KEY=your-api-key-here

Usage

Run the script:

python export_linear_issues.py

The script will:

1. Calculate the date 12 months ago from today
2. Connect to the Linear API using your API key
3. Fetch all closed issues (completed or canceled) from the last 12 months
4. Display progress as it fetches paginated results
5. Export the data to linear_closed_issues_last_12mo.csv

Output

The CSV file will contain the following columns:

• identifier - Issue identifier (e.g., ENG-123)
• title - Issue title
• completedAt - Timestamp when the issue was completed
• creator_name - Name of the person who created the issue
• assignee_name - Name of the person assigned to the issue
• url - Direct URL to the issue in Linear
• team_name - Name of the team the issue belongs to

Example Output

Linear Issues Export - Last 12 Months
============================================================
Fetching issues completed after: 2024-10-15T12:34:56.789012
============================================================
Page 1: Fetched 100 issues (Total: 100)
Page 2: Fetched 100 issues (Total: 200)
Page 3: Fetched 45 issues (Total: 245)
============================================================
Total issues fetched: 245
Successfully exported 245 issues to linear_closed_issues_last_12mo.csv
============================================================
Export completed successfully!

Code Quality Features

This script includes:

• Type hints: Full type annotations for better code clarity and IDE support
• Error handling: Comprehensive exception handling with specific error types
• Rate limiting: Automatic retry with exponential backoff for API rate limits (HTTP 429)
• Network resilience: Retry logic for timeouts and connection errors
• Constants: Configuration values defined as constants for easy customization
• Helper functions: Utility functions like safe_get_nested() for robust data access
• Timeout handling: 30-second timeout on API requests to prevent hanging
• Keyboard interrupt: Graceful handling of Ctrl+C
• Standards compliant: Uses Linear's required API key format (without Bearer prefix) and ISO 8601 datetime format

Troubleshooting

"LINEAR_API_KEY environment variable is not set"

Make sure you've either:

1. Created a .env file with your API key (recommended), or
2. Set the environment variable in your current shell session

You can verify it's set by running:

echo $LINEAR_API_KEY  # macOS/Linux
echo %LINEAR_API_KEY%  # Windows CMD
echo $env:LINEAR_API_KEY  # Windows PowerShell

"API request failed with status 401"

Your API key is invalid or expired. Generate a new key from Linear Settings → API.

"API request failed with status 403"

Your API key doesn't have permission to read issues. Check your API key permissions in Linear.

"Rate limit hit" messages

If you see "Rate limit hit. Retrying..." messages, the script is working correctly. Linear's API has rate limits to prevent abuse. The script will automatically:

• Wait with exponential backoff (1s, 2s, 4s, 8s, 16s)
• Retry up to 5 times
• Continue fetching once the rate limit clears

This is normal behavior for large workspaces with many issues.

Script runs but exports 0 issues

Possible causes:

1. No issues were completed in the last 12 months
2. All completed issues are in states other than "completed" or "canceled"
3. API key doesn't have access to the workspace/teams with issues

License

MIT License - see LICENSE file for details.

Copyright (c) 2025 24Slides. This software is provided "as is" without warranty of any kind. You are free to use, modify, and distribute this software for any purpose, commercial or non-commercial.