Engineering

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

GET
GET
GET
GET
GET
GET
GET
GET
GET

Retrieve engineering analytics author workflow

One author's estimated CI cost split by workflow over a window (date_from default -30d), highest spend first. Runs are attributed to the author through their pull requests (attribution is by PR number). Returns an empty list when the job-level source isn't synced.

Required API key scopes

engineering_analytics:read

Query parameters

  • author
    string
  • date_from
    string
  • date_to
    string
  • repo
    string
  • source_id
    string

Example request

GET /api/projects/:project_id/engineering_analytics/author_workflow_costs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/engineering_analytics/author_workflow_costs/

Example response

Status 200
RESPONSE
{
"workflow_name": "string",
"billable_minutes": 0.1,
"estimated_cost_usd": 0,
"costed_jobs": 0,
"unsettled_jobs": 0,
"excluded_jobs": 0
}
Status 400 Missing author, or invalid date or source_id.

Retrieve engineering analytics author workflow

One author's estimated CI cost split by workflow over a window (date_from default -30d), highest spend first. Runs are attributed to the author through their pull requests (attribution is by PR number). Returns an empty list when the job-level source isn't synced.

Required API key scopes

engineering_analytics:read

Query parameters

  • author
    string
  • date_from
    string
  • date_to
    string
  • repo
    string
  • source_id
    string

Example request

GET /api/projects/:project_id/engineering_analytics/author_workflow_costs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/engineering_analytics/author_workflow_costs/

Example response

Status 200
RESPONSE
{
"workflow_name": "string",
"billable_minutes": 0.1,
"estimated_cost_usd": 0,
"costed_jobs": 0,
"unsettled_jobs": 0,
"excluded_jobs": 0
}
Status 400 Missing author, or invalid date or source_id.

Retrieve engineering analytics broken

The broken-tests triage panel: live CI failures over the last 2 days grouped into distinct failures (by test id + normalized error signature) and classified by how each is behaving right now — breaking trunk, a new failure spreading across branches, probably-resolved, flaky, or one PR's own problem — ranked with the most urgent first. Also returns breaking_master_jobs, the default-branch jobs whose latest run is red. Reach for this to answer 'what CI failures should I care about right now'; expand a row's latest_run_id via run_failure_logs for the failing lines. Fingerprinting is pytest-only for now (jest/playwright/cargo failures aren't grouped yet), and the breaking/resolved distinction needs the job-level source synced — without it those failures fall through to flaky/pr_only rather than being misreported.

Required API key scopes

engineering_analytics:read

Query parameters

  • repo
    string
  • source_id
    string

Response


Example request

GET /api/projects/:project_id/engineering_analytics/broken_tests
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/engineering_analytics/broken_tests/

Example response

Status 200
RESPONSE
{
"rows": [
{
"fingerprint": "string",
"test_id": "string",
"error_signature": "string",
"job_name": "string",
"repo": "string",
"state": "breaking_master",
"first_seen": "2019-08-24T14:15:22Z",
"last_seen": "2019-08-24T14:15:22Z",
"occurrences": 0,
"branches": 0,
"master_hits": 0,
"latest_run_id": 0,
"latest_branch": "string",
"trend_24h": [
0
]
}
],
"breaking_master_jobs": [
"string"
],
"window_days": 0,
"truncated": true,
"limit": 0
}
Status 400 Invalid source_id.

Retrieve engineering analytics broken

The broken-tests triage panel: live CI failures over the last 2 days grouped into distinct failures (by test id + normalized error signature) and classified by how each is behaving right now — breaking trunk, a new failure spreading across branches, probably-resolved, flaky, or one PR's own problem — ranked with the most urgent first. Also returns breaking_master_jobs, the default-branch jobs whose latest run is red. Reach for this to answer 'what CI failures should I care about right now'; expand a row's latest_run_id via run_failure_logs for the failing lines. Fingerprinting is pytest-only for now (jest/playwright/cargo failures aren't grouped yet), and the breaking/resolved distinction needs the job-level source synced — without it those failures fall through to flaky/pr_only rather than being misreported.

Required API key scopes

engineering_analytics:read

Query parameters

  • repo
    string
  • source_id
    string

Response


Example request

GET /api/projects/:project_id/engineering_analytics/broken_tests
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/engineering_analytics/broken_tests/

Example response

Status 200
RESPONSE
{
"rows": [
{
"fingerprint": "string",
"test_id": "string",
"error_signature": "string",
"job_name": "string",
"repo": "string",
"state": "breaking_master",
"first_seen": "2019-08-24T14:15:22Z",
"last_seen": "2019-08-24T14:15:22Z",
"occurrences": 0,
"branches": 0,
"master_hits": 0,
"latest_run_id": 0,
"latest_branch": "string",
"trend_24h": [
0
]
}
],
"breaking_master_jobs": [
"string"
],
"window_days": 0,
"truncated": true,
"limit": 0
}
Status 400 Invalid source_id.

Retrieve engineering analytics ci signals config

Return the atomic CI Signals configuration and aggregate GitHub warehouse sync status.

Required API key scopes

engineering_analytics:read

Response


Example request

GET /api/projects/:project_id/engineering_analytics/ci-signals-config
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/engineering_analytics/ci-signals-config/

Example response

Status 200
RESPONSE
{
"configured": true,
"enabled": true,
"sync_status": "running"
}

Retrieve engineering analytics ci signals config

Return the atomic CI Signals configuration and aggregate GitHub warehouse sync status.

Required API key scopes

engineering_analytics:read

Response


Example request

GET /api/projects/:project_id/engineering_analytics/ci-signals-config
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/engineering_analytics/ci-signals-config/

Example response

Status 200
RESPONSE
{
"configured": true,
"enabled": true,
"sync_status": "running"
}

Retrieve engineering analytics ci

Headline counts for the open-PR backlog: open PRs, distinct repos, stuck PRs (open, non-draft, non-bot, older than 7 days), and PRs with failing CI. The failing-CI count rests on the head-SHA join and can lag until late CI completions settle.

Required API key scopes

engineering_analytics:read

Query parameters

  • repo
    string
  • source_id
    string

Response


Example request

GET /api/projects/:project_id/engineering_analytics/ci_cards
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/engineering_analytics/ci_cards/

Example response

Status 200
RESPONSE
{
"open_prs": 0,
"repos": 0,
"stuck": 0,
"failing_ci": 0
}
Status 400 Invalid source_id.

Retrieve engineering analytics ci

Headline counts for the open-PR backlog: open PRs, distinct repos, stuck PRs (open, non-draft, non-bot, older than 7 days), and PRs with failing CI. The failing-CI count rests on the head-SHA join and can lag until late CI completions settle.

Required API key scopes

engineering_analytics:read

Query parameters

  • repo
    string
  • source_id
    string

Response


Example request

GET /api/projects/:project_id/engineering_analytics/ci_cards
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/engineering_analytics/ci_cards/

Example response

Status 200
RESPONSE
{
"open_prs": 0,
"repos": 0,
"stuck": 0,
"failing_ci": 0
}
Status 400 Invalid source_id.

Retrieve engineering analytics ci failure

The thinned CI failure logs for a pull request, grouped by failed job. Resolves the PR to its workflow runs via the pull_requests association (all of the PR's pushes, not just the latest commit), then reads the Logs product joined on run_id. Returns failed jobs only (the worker fetches logs for failures); logs_available is false when CI hasn't failed, the logs aged out of the short Logs retention, or a fork PR has no run association. Each line carries its original 1-based line number in the full pre-thinning log; lines are the failure region (errors plus surrounding context, with omission markers), capped per job and overall.

Required API key scopes

engineering_analytics:read

Query parameters

  • pr_number
    integer
  • repo
    string
  • source_id
    string

Response


Example request

GET /api/projects/:project_id/engineering_analytics/ci_failure_logs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/engineering_analytics/ci_failure_logs/

Example response

Status 200
RESPONSE
{
"repo": {
"provider": "string",
"owner": "string",
"name": "string"
},
"jobs": [
{
"lines": [
{
"original_line": 0,
"text": "string"
}
],
"job_id": 0,
"run_id": 0,
"conclusion": "string",
"branch": "string",
"original_total_lines": 0,
"line_count": 0,
"truncated": true
}
],
"pr_number": 0,
"runs_attributed": 0,
"logs_available": true,
"truncated": true
}
Status 400 Missing pr_number/repo, or invalid repo or source_id.

Retrieve engineering analytics ci failure

The thinned CI failure logs for a pull request, grouped by failed job. Resolves the PR to its workflow runs via the pull_requests association (all of the PR's pushes, not just the latest commit), then reads the Logs product joined on run_id. Returns failed jobs only (the worker fetches logs for failures); logs_available is false when CI hasn't failed, the logs aged out of the short Logs retention, or a fork PR has no run association. Each line carries its original 1-based line number in the full pre-thinning log; lines are the failure region (errors plus surrounding context, with omission markers), capped per job and overall.

Required API key scopes

engineering_analytics:read

Query parameters

  • pr_number
    integer
  • repo
    string
  • source_id
    string

Response


Example request

GET /api/projects/:project_id/engineering_analytics/ci_failure_logs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/engineering_analytics/ci_failure_logs/

Example response

Status 200
RESPONSE
{
"repo": {
"provider": "string",
"owner": "string",
"name": "string"
},
"jobs": [
{
"lines": [
{
"original_line": 0,
"text": "string"
}
],
"job_id": 0,
"run_id": 0,
"conclusion": "string",
"branch": "string",
"original_total_lines": 0,
"line_count": 0,
"truncated": true
}
],
"pr_number": 0,
"runs_attributed": 0,
"logs_available": true,
"truncated": true
}
Status 400 Missing pr_number/repo, or invalid repo or source_id.

Retrieve engineering analytics current branch

Current default-branch CI verdict over the fixed last-24-hours window. Counts every workflow whose latest completed run failed or timed out; failing workflow names are a bounded preview. The default branch is detected from the same window, independently of analytics date filters.

Required API key scopes

engineering_analytics:read

Query parameters

  • repo
    string
  • source_id
    string

Response


Example request

GET /api/projects/:project_id/engineering_analytics/current_branch_health
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/engineering_analytics/current_branch_health/

Example response

Status 200
RESPONSE
{
"default_branch": "string",
"settled_workflows": 0,
"failing_workflows": 0,
"failing_workflow_names": [
"string"
]
}
Status 400 Invalid source_id.

Retrieve engineering analytics current branch

Current default-branch CI verdict over the fixed last-24-hours window. Counts every workflow whose latest completed run failed or timed out; failing workflow names are a bounded preview. The default branch is detected from the same window, independently of analytics date filters.

Required API key scopes

engineering_analytics:read

Query parameters

  • repo
    string
  • source_id
    string

Response


Example request

GET /api/projects/:project_id/engineering_analytics/current_branch_health
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/engineering_analytics/current_branch_health/

Example response

Status 200
RESPONSE
{
"default_branch": "string",
"settled_workflows": 0,
"failing_workflows": 0,
"failing_workflow_names": [
"string"
]
}
Status 400 Invalid source_id.

Retrieve engineering analytics flaky

The active test-health queue: backend tests worth acting on now, from the per-test CI spans, over a window (default -7d, maximum 30 days). Evidence is counted per CI run, never per span or run attempt. A test is a 'confirmed_flake' when one commit both failed and passed it (a 'Re-run failed jobs' attempt went green, or an in-job retry recovered it); 'quarantined' when it fails while masked as xfail; otherwise 'suspected_regression'. It qualifies on any same-commit recovery, any master/main failure, an xfail, or failures on at least min_failed_prs distinct PRs. Counts are absolute, never rates: CI emits a span for every failure but only for passes slow enough to clear the emitter's duration threshold, so there is no execution denominator. 'suspected_regression' means no recovery was recorded in this data, not that the test never flakes.

Required API key scopes

engineering_analytics:read

Query parameters

  • date_from
    string
  • date_to
    string
  • limit
    integer
  • min_failed_prs
    integer
  • repo
    string
  • source_id
    string

Response


Example request

GET /api/projects/:project_id/engineering_analytics/flaky_tests
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/engineering_analytics/flaky_tests/

Example response

Status 200
RESPONSE
{
"items": [
{
"nodeid": "string",
"selector": "string",
"classification": "confirmed_flake",
"same_commit_recovery_run_count": 0,
"failed_run_count": 0,
"failed_pr_count": 0,
"master_failed_run_count": 0,
"quarantined_failed_run_count": 0,
"last_signal_at": "2019-08-24T14:15:22Z"
}
],
"truncated": true,
"limit": 0
}
Status 400 Invalid date, threshold, limit, or source_id, or a window longer than 30 days.

Retrieve engineering analytics flaky

The active test-health queue: backend tests worth acting on now, from the per-test CI spans, over a window (default -7d, maximum 30 days). Evidence is counted per CI run, never per span or run attempt. A test is a 'confirmed_flake' when one commit both failed and passed it (a 'Re-run failed jobs' attempt went green, or an in-job retry recovered it); 'quarantined' when it fails while masked as xfail; otherwise 'suspected_regression'. It qualifies on any same-commit recovery, any master/main failure, an xfail, or failures on at least min_failed_prs distinct PRs. Counts are absolute, never rates: CI emits a span for every failure but only for passes slow enough to clear the emitter's duration threshold, so there is no execution denominator. 'suspected_regression' means no recovery was recorded in this data, not that the test never flakes.

Required API key scopes

engineering_analytics:read

Query parameters

  • date_from
    string
  • date_to
    string
  • limit
    integer
  • min_failed_prs
    integer
  • repo
    string
  • source_id
    string

Response


Example request

GET /api/projects/:project_id/engineering_analytics/flaky_tests
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/engineering_analytics/flaky_tests/

Example response

Status 200
RESPONSE
{
"items": [
{
"nodeid": "string",
"selector": "string",
"classification": "confirmed_flake",
"same_commit_recovery_run_count": 0,
"failed_run_count": 0,
"failed_pr_count": 0,
"master_failed_run_count": 0,
"quarantined_failed_run_count": 0,
"last_signal_at": "2019-08-24T14:15:22Z"
}
],
"truncated": true,
"limit": 0
}
Status 400 Invalid date, threshold, limit, or source_id, or a window longer than 30 days.

Retrieve engineering analytics job

Per-job aggregates for one workflow over a window (default -30d), one row per de-sharded job name (matrix shards aggregate together), busiest first: queue p50, duration p50/p95, failure rate, retry pressure, run share (below 1.0 = conditional job), and billable cost. Jobs always need their run as context — this is the aggregate view; use workflow_jobs for one run's jobs. Empty when the job-level source isn't synced.

Required API key scopes

engineering_analytics:read

Query parameters

  • branch
    string
  • date_from
    string
  • date_to
    string
  • repo
    string
  • source_id
    string
  • workflow_name
    string

Example request

GET /api/projects/:project_id/engineering_analytics/job_aggregates
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/engineering_analytics/job_aggregates/

Example response

Status 200
RESPONSE
{
"job_name": "string",
"job_count": 0,
"shard_count": 0,
"runs_in": 0,
"run_share": 0,
"queue_p50_seconds": 0,
"p50_seconds": 0,
"p95_seconds": 0,
"failure_rate": 0,
"retry_job_count": 0,
"billable_minutes": 0,
"estimated_cost_usd": 0
}
Status 400 Missing workflow_name, or invalid date or source_id.

Retrieve engineering analytics job

Per-job aggregates for one workflow over a window (default -30d), one row per de-sharded job name (matrix shards aggregate together), busiest first: queue p50, duration p50/p95, failure rate, retry pressure, run share (below 1.0 = conditional job), and billable cost. Jobs always need their run as context — this is the aggregate view; use workflow_jobs for one run's jobs. Empty when the job-level source isn't synced.

Required API key scopes

engineering_analytics:read

Query parameters

  • branch
    string
  • date_from
    string
  • date_to
    string
  • repo
    string
  • source_id
    string
  • workflow_name
    string

Example request

GET /api/projects/:project_id/engineering_analytics/job_aggregates
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/engineering_analytics/job_aggregates/

Example response

Status 200
RESPONSE
{
"job_name": "string",
"job_count": 0,
"shard_count": 0,
"runs_in": 0,
"run_share": 0,
"queue_p50_seconds": 0,
"p50_seconds": 0,
"p95_seconds": 0,
"failure_rate": 0,
"retry_job_count": 0,
"billable_minutes": 0,
"estimated_cost_usd": 0
}
Status 400 Missing workflow_name, or invalid date or source_id.

Retrieve engineering analytics master

Default-branch failures over a window (default -24h), grouped error-tracking style by (workflow, de-sharded failing job) with a run count and first/last seen, newest group first. branch overrides the detected default branch. PR-branch failures are deliberately excluded — at monorepo volume a flat feed is a firehose; those surface per PR. Groups degrade to workflow level (failed_job '') when the job-level source isn't synced.

Required API key scopes

engineering_analytics:read

Query parameters

  • branch
    string
  • date_from
    string
  • date_to
    string
  • repo
    string
  • source_id
    string

Example request

GET /api/projects/:project_id/engineering_analytics/master_failures
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/engineering_analytics/master_failures/

Example response

Status 200
RESPONSE
{
"repo": {
"provider": "string",
"owner": "string",
"name": "string"
},
"workflow_name": "string",
"failed_job": "string",
"run_count": 0,
"first_seen": "2019-08-24T14:15:22Z",
"last_seen": "2019-08-24T14:15:22Z",
"latest_run_id": 0
}
Status 400 Invalid date_from, date_to, or source_id, or a window over 366 days.

Retrieve engineering analytics master

Default-branch failures over a window (default -24h), grouped error-tracking style by (workflow, de-sharded failing job) with a run count and first/last seen, newest group first. branch overrides the detected default branch. PR-branch failures are deliberately excluded — at monorepo volume a flat feed is a firehose; those surface per PR. Groups degrade to workflow level (failed_job '') when the job-level source isn't synced.

Required API key scopes

engineering_analytics:read

Query parameters

  • branch
    string
  • date_from
    string
  • date_to
    string
  • repo
    string
  • source_id
    string

Example request

GET /api/projects/:project_id/engineering_analytics/master_failures
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/engineering_analytics/master_failures/

Example response

Status 200
RESPONSE
{
"repo": {
"provider": "string",
"owner": "string",
"name": "string"
},
"workflow_name": "string",
"failed_job": "string",
"run_count": 0,
"first_seen": "2019-08-24T14:15:22Z",
"last_seen": "2019-08-24T14:15:22Z",
"latest_run_id": 0
}
Status 400 Invalid date_from, date_to, or source_id, or a window over 366 days.

Community questions