Functory
functory.
All Articles
7 min read
Functory

Python Jira cycle time report API for quarterly engineering reviews

This article shows how to take raw Jira project-board data (issues with status history), compute meaningful cycle-time metrics, and expose that result as a reproducible API. The focus is practical: concrete inputs (Jira JSON or CSV exports), deterministic transformations (In Progress → Done cycle time, percentiles, throughput), and a minimal Python implementation that you can turn into a hosted API in under 30 minutes.

Long-tail search phrases used naturally here: python jira cycle time report, jira cycle time api python, publish jira report as api. If you want fast, audited quarterly metrics for engineering reviews or investor updates without spreadsheets, this pattern is for you.

What this function expects and produces

Input formats supported (concrete):

  • Jira REST API JSON for issue search (fields: key, created, resolutiondate, status, changelog.histories) — typical export from /rest/api/2/search?expand=changelog
  • CSV export with columns: key, created, resolved, status_history_json (a JSON string of timestamped statuses), assignee, labels, sprint

Transformations performed (concrete):

  • Parse status transitions to find first entry into a configured start state (default: "In Progress") and first entry into an end state (default: "Done" or "Resolved").
  • Compute cycle_time_days = (end_timestamp - start_timestamp).total_seconds() / 86400. If start or end is missing, apply configurable fallback (created→resolved or drop record).
  • Group by quarter (e.g., 2025-Q1), compute count, throughput (issues completed), mean, median, 75th and 95th percentiles, and average wait time (time in To Do statuses).
  • Output JSON or CSV with rows: quarter, completed_count, throughput_per_week, median_cycle_days, mean_cycle_days, p75_cycle_days, p95_cycle_days, notes.

Real-world scenario

Company: indie SaaS startup with a single product team. They keep a Jira board with 1,200 tickets (issues) in a quarter. Each issue's changelog contains 6–20 status changes. Stakeholders ask during quarterly reviews: "What is median cycle time for shipped tasks by quarter? Have we improved since last quarter?"

Concrete input example (one issue, JSON):

{
  "key": "PROJ-123",
  "created": "2025-01-02T09:15:00.000+0000",
  "resolutiondate": "2025-02-18T16:20:00.000+0000",
  "changelog": {
    "histories": [
      {"created":"2025-01-05T10:00:00.000+0000","items":[{"field":"status","fromString":"To Do","toString":"In Progress"}]},
      {"created":"2025-02-17T14:00:00.000+0000","items":[{"field":"status","fromString":"In Progress","toString":"Done"}]}
    ]
  },
  "fields": {"assignee":"alice","labels":["bug"],"sprint":"Sprint 14"}
}

Expected output row (JSON):

{
  "quarter": "2025-Q1",
  "completed_count": 256,
  "throughput_per_week": 20.5,
  "median_cycle_days": 6.2,
  "mean_cycle_days": 9.8,
  "p75_cycle_days": 12.4,
  "p95_cycle_days": 27.1
}

Example dataset and the specific problem

Fabricated but realistic dataset:

  • Size: 1,200 Jira issues completed in a quarter (2025-Q1).
  • Fields: key (string), created (ISO8601), resolutiondate (ISO8601), changelog.histories (array of {created, items}), fields.assignee, fields.labels, fields.components.
  • Problem: management needs an auditable cycle-time report for the quarterly review and wants an API they can call from a CI job or a Slack bot. Current process is manual CSV export + Excel pivot tables updated by an engineering manager (6 hours/quarter).

This function solves it by removing manual CSV manipulation and producing consistent metrics every time the pipeline runs.

Step-by-step mini workflow

  1. Export issues from Jira REST API with changelog: GET /rest/api/2/search?jql=project=PROJ%20AND%20status%20in%20(Closed,Done)&expand=changelog
  2. Run the Python processor to parse changelog, compute cycle_time_days for each issue, and assign it to a quarter.
  3. Aggregate metrics (median, p75, p95, throughput_per_week) and serialize as JSON or CSV.
  4. Optionally publish result to a BI dashboard or call the Functory-hosted API from a CI job to include the metrics in a quarterly report PDF.
  5. Use the same script to compute rolling 12-week windows for trend charts.

Processing algorithm (high level)

1. For each issue, parse changelog.histories in chronological order. 2. Find timestamp of first transition into START_STATUS (default "In Progress"). 3. Find timestamp of first transition into END_STATUS (default "Done" or resolutiondate). 4. If both timestamps exist, cycle_time = end - start; else, use fallback or mark as excluded. 5. Convert cycle_time to days; bucket by ISO quarter; compute aggregate stats per quarter.

Code example (compute core metrics)

The snippet below shows a small, runnable function using pandas that accepts a list of issue dicts and returns a DataFrame of quarterly metrics.

import pandas as pd
from datetime import datetime
from dateutil import parser
import numpy as np

def compute_cycle_metrics(issues, start_status='In Progress', end_statuses=('Done','Resolved')):
    rows = []
    for issue in issues:
        key = issue.get('key')
        created = parser.isoparse(issue.get('created'))
        resolution = issue.get('resolutiondate')
        res_dt = parser.isoparse(resolution) if resolution else None
        start_ts = None
        end_ts = None
        for hist in issue.get('changelog', {}).get('histories', []):
            ts = parser.isoparse(hist['created'])
            for item in hist.get('items', []):
                if item.get('field') == 'status':
                    to = item.get('toString')
                    if to == start_status and start_ts is None:
                        start_ts = ts
                    if to in end_statuses and end_ts is None:
                        end_ts = ts
        # fallback: use created/resolution
        if start_ts is None:
            start_ts = created
        if end_ts is None and res_dt is not None:
            end_ts = res_dt
        if start_ts and end_ts and end_ts > start_ts:
            days = (end_ts - start_ts).total_seconds() / 86400.0
            quarter = f"{start_ts.year}-Q{((start_ts.month-1)//3)+1}"
            rows.append({'key': key, 'quarter': quarter, 'cycle_days': days})
    df = pd.DataFrame(rows)
    if df.empty:
        return pd.DataFrame()
    agg = df.groupby('quarter').cycle_days.agg(['count', 'mean', 'median'])
    agg['p75'] = df.groupby('quarter').cycle_days.quantile(0.75)
    agg['p95'] = df.groupby('quarter').cycle_days.quantile(0.95)
    # throughput per week (approx): count / 13 (quarters ~13 weeks)
    agg['throughput_per_week'] = agg['count'] / 13.0
    agg = agg.rename(columns={'count':'completed_count','mean':'mean_cycle_days','median':'median_cycle_days'})
    return agg.reset_index()

# Example usage
if __name__ == '__main__':
    sample_issues = [
        {
            'key':'PROJ-1',
            'created':'2025-01-05T10:00:00.000+00:00',
            'resolutiondate':'2025-01-12T15:00:00.000+00:00',
            'changelog':{'histories':[{'created':'2025-01-06T09:00:00+00:00','items':[{'field':'status','toString':'In Progress'}]},{'created':'2025-01-12T14:00:00+00:00','items':[{'field':'status','toString':'Done'}]}]}
        },
        {
            'key':'PROJ-2',
            'created':'2025-02-01T11:00:00.000+00:00',
            'resolutiondate':None,
            'changelog':{'histories':[]}
        }
    ]
    print(compute_cycle_metrics(sample_issues).to_dict(orient='records'))

How Functory Makes It Easy

To publish this as a Functory function you wrap the core logic into a single Python main(...) entrypoint. The main parameters could be: jira_export (FilePath or URL string), start_status (str), end_statuses (comma-separated str), output_format (json/csv). On Functory you must pick an exact Python version (for example, 3.11.11) and add a requirements.txt with pinned packages such as pandas==2.2.2 and python-dateutil==2.8.2. Functory will call main(...) directly — its parameters become the web UI fields and the JSON body of the HTTP API. If main(...) returns a path-like string (e.g., '/tmp/report.csv'), Functory exposes that file as a downloadable result.

Concrete publishing steps on Functory:

  • Choose runtime: Python 3.11.11
  • Create requirements.txt with exact pins: pandas==2.2.2\npython-dateutil==2.8.2
  • Place the code with a main(jira_export: str, start_status: str='In Progress', end_statuses: str='Done,Resolved') function that reads the file/URL, runs compute_cycle_metrics, writes CSV, and returns the file path.
  • Publish: Functory provides automatic UI input fields for jira_export and start_status, and an HTTP endpoint you can call from CI or an LLM agent. It handles execution, logs printed via print(), autoscaling, and pay-per-use billing.

Benefits on Functory: no servers to manage, automatic CPU allocation for batch processing, predictable billing, and quick chaining — you can call this function from another Functory function (pre-processing → metrics → PDF report) to build a complete, serverless reporting pipeline.

Alternatives and why this approach

Developers currently create cycle-time reports using: (1) manual CSV exports + Excel pivot tables, (2) BI tools like Power BI/Tableau that require connectors and licensing, (3) custom scripts running on a VM or CI pipelines. Manual Excel is error-prone and hard to reproduce. BI tools can be heavy and expensive for small teams. VM-hosted scripts require ops work. A small Python function exposed as an API is reproducible, inexpensive, automatable, and integrates with CI and Slack. Hosting on a NoOps platform like Functory removes operational burden while providing programmatic access for automated quarterly reports.

Business impact

Quantified benefit: replacing a 6-hour manual reporting task with an automated API reduces engineer or manager time by ~75% and cuts quarterly reporting effort from 6 hours to ~1.5 hours for setup and validation — saving ~4.5 person-hours per quarter (~18 hours/year). For a team with a $60/hour fully loaded cost, that's ~$1,080/year in direct labor savings, plus faster, evidence-based decisions.

Industry signal: According to a 2024 State of DevOps-style report, teams that instrument and measure cycle time improve lead time by ~30% year-over-year when using regular metrics-driven reviews (Source: 2024 DevOps Metrics Report).

Comparison to other methods

Manual spreadsheets: quick to start but fragile and non-repeatable. BI tools: great for visual dashboards but require connectors and licenses and are less suitable for quick programmatic consumption. Custom scripts on VMs: flexible but require ops overhead. The small, single-file Python + hosted API approach is reproducible, auditable (source + inputs), and cheap to operate; it fits indie hacker and remote-first teams that need reliable quarterly reviews without hiring DevOps staff.

Conclusion: Parsing Jira changelogs and computing cycle time metrics in Python is a concise, high-impact automation that yields auditable quarterly reports. Next steps: connect the function to your Jira export, tune start/end states for your workflow (e.g., "Ready for QA" → "Done"), and publish on a NoOps platform like Functory for scheduled runs and API access. Try implementing the compute_cycle_metrics function above, run it on one quarter of data, and publish the result as an API — then iterate on percentiles and segmentation (by team, component, or assignee) to get actionable insights.

Thanks for reading.