Engineering API Reference

Retrieve engineering analytics pr

Estimated CI cost for a pull request, summed over the jobs of all its workflow runs. Billable self-hosted Linux runners only — provider-hosted (free GitHub-hosted) and non-Linux jobs are excluded. Every figure is zero/null with jobs_available false when the job-level source isn't synced yet. llm_spend carries the agent LLM token spend attributed to the PR by git branch, or null when no $ai_generation event matched.

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/pr_cost
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/pr_cost/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/engineering_analytics/pr_cost/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "by_workflow": [
    {
      "workflow_name": "string",
      "billable_minutes": 0.1,
      "estimated_cost_usd": 0,
      "costed_jobs": 0,
      "unsettled_jobs": 0,
      "excluded_jobs": 0
    }
  ],
  "by_run": [
    {
      "run_id": 0,
      "run_attempt": 0,
      "billable_minutes": 0.1,
      "estimated_cost_usd": 0
    }
  ],
  "llm_spend": {
    "cost_usd": 0.1,
    "input_tokens": 0,
    "output_tokens": 0,
    "generations": 0
  },
  "jobs_available": true,
  "billable_minutes": 0.1,
  "estimated_cost_usd": 0,
  "costed_jobs": 0,
  "unsettled_jobs": 0,
  "excluded_jobs": 0
}

Status 400 Missing pr_number/repo, or invalid repo or source_id.

Retrieve engineering analytics pr

Estimated CI cost for a pull request, summed over the jobs of all its workflow runs. Billable self-hosted Linux runners only — provider-hosted (free GitHub-hosted) and non-Linux jobs are excluded. Every figure is zero/null with jobs_available false when the job-level source isn't synced yet. llm_spend carries the agent LLM token spend attributed to the PR by git branch, or null when no $ai_generation event matched.

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/pr_cost
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/pr_cost/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/engineering_analytics/pr_cost/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "by_workflow": [
    {
      "workflow_name": "string",
      "billable_minutes": 0.1,
      "estimated_cost_usd": 0,
      "costed_jobs": 0,
      "unsettled_jobs": 0,
      "excluded_jobs": 0
    }
  ],
  "by_run": [
    {
      "run_id": 0,
      "run_attempt": 0,
      "billable_minutes": 0.1,
      "estimated_cost_usd": 0
    }
  ],
  "llm_spend": {
    "cost_usd": 0.1,
    "input_tokens": 0,
    "output_tokens": 0,
    "generations": 0
  },
  "jobs_available": true,
  "billable_minutes": 0.1,
  "estimated_cost_usd": 0,
  "costed_jobs": 0,
  "unsettled_jobs": 0,
  "excluded_jobs": 0
}

Status 400 Missing pr_number/repo, or invalid repo or source_id.

Retrieve engineering analytics pr

The timeline of a single pull request: header plus ordered events (opened, CI started/finished, merged or closed). Use this to answer 'where is this PR stuck and what happened to it'. This is a partial view: review and comment events are not yet available.

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/pr_lifecycle
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/pr_lifecycle/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/engineering_analytics/pr_lifecycle/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "pull_request": {
    "author": {
      "handle": "string",
      "display_name": "string",
      "avatar_url": "string",
      "is_bot": true
    },
    "repo": {
      "provider": "string",
      "owner": "string",
      "name": "string"
    },
    "id": 0,
    "number": 0,
    "title": "string",
    "state": "open",
    "is_draft": true,
    "created_at": "2019-08-24T14:15:22Z",
    "merged_at": "2019-08-24T14:15:22Z",
    "closed_at": "2019-08-24T14:15:22Z"
  },
  "events": [
    {
      "kind": "opened",
      "at": "2019-08-24T14:15:22Z",
      "detail": "string",
      "run_id": 0
    }
  ],
  "metric_quality": "precise"
}

Status 400 Missing pr_number/repo, or invalid repo or source_id.

Status 404 No pull request with that number in the warehouse.

Retrieve engineering analytics pr

The timeline of a single pull request: header plus ordered events (opened, CI started/finished, merged or closed). Use this to answer 'where is this PR stuck and what happened to it'. This is a partial view: review and comment events are not yet available.

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/pr_lifecycle
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/pr_lifecycle/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/engineering_analytics/pr_lifecycle/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "pull_request": {
    "author": {
      "handle": "string",
      "display_name": "string",
      "avatar_url": "string",
      "is_bot": true
    },
    "repo": {
      "provider": "string",
      "owner": "string",
      "name": "string"
    },
    "id": 0,
    "number": 0,
    "title": "string",
    "state": "open",
    "is_draft": true,
    "created_at": "2019-08-24T14:15:22Z",
    "merged_at": "2019-08-24T14:15:22Z",
    "closed_at": "2019-08-24T14:15:22Z"
  },
  "events": [
    {
      "kind": "opened",
      "at": "2019-08-24T14:15:22Z",
      "detail": "string",
      "run_id": 0
    }
  ],
  "metric_quality": "precise"
}

Status 400 Missing pr_number/repo, or invalid repo or source_id.

Status 404 No pull request with that number in the warehouse.

Retrieve engineering analytics pr

Every workflow run attributed to a pull request, across all its commits (grouped by head SHA client-side), newest first. Run-level only.

Required API key scopes

engineering_analytics:read

Query parameters

pr_number
integer
repo
string
source_id
string

Example request

GET /api/projects/:project_id/engineering_analytics/pr_runs
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/pr_runs/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/engineering_analytics/pr_runs/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "repo": {
    "provider": "string",
    "owner": "string",
    "name": "string"
  },
  "id": 0,
  "workflow_name": "string",
  "head_sha": "string",
  "head_branch": "string",
  "status": "string",
  "conclusion": "string",
  "run_started_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "duration_seconds": 0,
  "run_attempt": 0,
  "pr_number": 0
}

Status 400 Missing pr_number/repo, or invalid repo or source_id.

Retrieve engineering analytics pr

Every workflow run attributed to a pull request, across all its commits (grouped by head SHA client-side), newest first. Run-level only.

Required API key scopes

engineering_analytics:read

Query parameters

pr_number
integer
repo
string
source_id
string

Example request

GET /api/projects/:project_id/engineering_analytics/pr_runs
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/pr_runs/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/engineering_analytics/pr_runs/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "repo": {
    "provider": "string",
    "owner": "string",
    "name": "string"
  },
  "id": 0,
  "workflow_name": "string",
  "head_sha": "string",
  "head_branch": "string",
  "status": "string",
  "conclusion": "string",
  "run_started_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "duration_seconds": 0,
  "run_attempt": 0,
  "pr_number": 0
}

Status 400 Missing pr_number/repo, or invalid repo or source_id.

Retrieve engineering analytics pull

Open pull requests plus any merged or closed since date_from (default -30d), newest first, each with its head-SHA CI rollup. The list is capped; when more match, truncated is true and the ci_cards counts can exceed it. open_to_merge_seconds is coarse — it fuses draft and ready-for-review time; CI counts can lag until late completions settle.

Required API key scopes

engineering_analytics:read

Query parameters

author
string
date_from
string
repo
string
source_id
string

Response

Example request

GET /api/projects/:project_id/engineering_analytics/pull_requests
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/pull_requests/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/engineering_analytics/pull_requests/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "items": [
    {
      "author": {
        "handle": "string",
        "display_name": "string",
        "avatar_url": "string",
        "is_bot": true
      },
      "repo": {
        "provider": "string",
        "owner": "string",
        "name": "string"
      },
      "ci": {
        "runs": 0,
        "passing": 0,
        "failing": 0,
        "pending": 0,
        "failing_workflows": [
          "string"
        ]
      },
      "push_history": [
        {
          "head_sha": "string",
          "started_at": "2019-08-24T14:15:22Z",
          "wall_seconds": 0,
          "failed": true,
          "pending": true
        }
      ],
      "number": 0,
      "title": "string",
      "state": "open",
      "is_draft": true,
      "created_at": "2019-08-24T14:15:22Z",
      "merged_at": "2019-08-24T14:15:22Z",
      "open_to_merge_seconds": 0,
      "labels": [
        "string"
      ],
      "pushes": 0,
      "rerun_cycles": 0,
      "estimated_cost_usd": 0,
      "billable_minutes": 0
    }
  ],
  "truncated": true,
  "limit": 0
}

Status 400 Invalid date_from or source_id.

Retrieve engineering analytics pull

Open pull requests plus any merged or closed since date_from (default -30d), newest first, each with its head-SHA CI rollup. The list is capped; when more match, truncated is true and the ci_cards counts can exceed it. open_to_merge_seconds is coarse — it fuses draft and ready-for-review time; CI counts can lag until late completions settle.

Required API key scopes

engineering_analytics:read

Query parameters

author
string
date_from
string
repo
string
source_id
string

Response

Example request

GET /api/projects/:project_id/engineering_analytics/pull_requests
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/pull_requests/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/engineering_analytics/pull_requests/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "items": [
    {
      "author": {
        "handle": "string",
        "display_name": "string",
        "avatar_url": "string",
        "is_bot": true
      },
      "repo": {
        "provider": "string",
        "owner": "string",
        "name": "string"
      },
      "ci": {
        "runs": 0,
        "passing": 0,
        "failing": 0,
        "pending": 0,
        "failing_workflows": [
          "string"
        ]
      },
      "push_history": [
        {
          "head_sha": "string",
          "started_at": "2019-08-24T14:15:22Z",
          "wall_seconds": 0,
          "failed": true,
          "pending": true
        }
      ],
      "number": 0,
      "title": "string",
      "state": "open",
      "is_draft": true,
      "created_at": "2019-08-24T14:15:22Z",
      "merged_at": "2019-08-24T14:15:22Z",
      "open_to_merge_seconds": 0,
      "labels": [
        "string"
      ],
      "pushes": 0,
      "rerun_cycles": 0,
      "estimated_cost_usd": 0,
      "billable_minutes": 0
    }
  ],
  "truncated": true,
  "limit": 0
}

Status 400 Invalid date_from or source_id.

Retrieve engineering analytics

The repository's checked-in .test_quarantine.json: flaky tests temporarily quarantined with a hard expiry, classified by urgency (overdue, in grace, expiring soon, active). available is false when the repo has no quarantine file — that is not an error. Parsing is fail-open: malformed entries are reported in parse_errors while well-formed ones are kept.

Required API key scopes

engineering_analytics:read

Query parameters

repo
string
source_id
string

Response

Example request

GET /api/projects/:project_id/engineering_analytics/quarantine
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/quarantine/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/engineering_analytics/quarantine/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "entries": [
    {
      "id": "string",
      "runner": "string",
      "reason": "string",
      "owner": "string",
      "issue": "string",
      "added": "2019-08-24",
      "expires": "2019-08-24",
      "mode": "run",
      "lifecycle": "active",
      "days_until_expiry": 0,
      "selector_kind": "product"
    }
  ],
  "repo": {
    "provider": "string",
    "owner": "string",
    "name": "string"
  },
  "available": true,
  "parse_errors": [
    "string"
  ],
  "parse_warnings": [
    "string"
  ],
  "source_url": "string",
  "generated_at": "2019-08-24T14:15:22Z"
}

Status 400 Invalid repo or source_id.

Retrieve engineering analytics

The repository's checked-in .test_quarantine.json: flaky tests temporarily quarantined with a hard expiry, classified by urgency (overdue, in grace, expiring soon, active). available is false when the repo has no quarantine file — that is not an error. Parsing is fail-open: malformed entries are reported in parse_errors while well-formed ones are kept.

Required API key scopes

engineering_analytics:read

Query parameters

repo
string
source_id
string

Response

Example request

GET /api/projects/:project_id/engineering_analytics/quarantine
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/quarantine/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/engineering_analytics/quarantine/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "entries": [
    {
      "id": "string",
      "runner": "string",
      "reason": "string",
      "owner": "string",
      "issue": "string",
      "added": "2019-08-24",
      "expires": "2019-08-24",
      "mode": "run",
      "lifecycle": "active",
      "days_until_expiry": 0,
      "selector_kind": "product"
    }
  ],
  "repo": {
    "provider": "string",
    "owner": "string",
    "name": "string"
  },
  "available": true,
  "parse_errors": [
    "string"
  ],
  "parse_warnings": [
    "string"
  ],
  "source_url": "string",
  "generated_at": "2019-08-24T14:15:22Z"
}

Status 400 Invalid repo or source_id.

Create engineering analytics quarantine

Opens a pull request that edits the repository's checked-in .test_quarantine.json — and, for a new quarantine, a tracking issue the PR links but does not close. The file stays the source of truth that CI enforces; this never bypasses it. A quarantine only affects CI runs that start after the PR merges.

Required API key scopes

engineering_analytics:write

Request parameters

operation
selector
string
repo
stringnull
reason
string
owner
string
issue
string
expires
stringnull
mode

Response

Example request

POST /api/projects/:project_id/engineering_analytics/quarantine/request
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/engineering_analytics/quarantine/request/\
	-d operation=undefined,\
	-d selector="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/engineering_analytics/quarantine/request/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"selector": "string"
	}
).json()

Example response

Status 201 The opened pull request, plus the tracking issue for a new quarantine.

RESPONSE
{
  "pr_url": "string",
  "issue_url": "string",
  "branch": "string"
}

Status 400 Invalid input, or the write could not be completed (no GitHub App installed on the repo's org, a malformed quarantine file, or a GitHub failure). The detail message is safe to show.

Create engineering analytics quarantine

Opens a pull request that edits the repository's checked-in .test_quarantine.json — and, for a new quarantine, a tracking issue the PR links but does not close. The file stays the source of truth that CI enforces; this never bypasses it. A quarantine only affects CI runs that start after the PR merges.

Required API key scopes

engineering_analytics:write

Request parameters

operation
selector
string
repo
stringnull
reason
string
owner
string
issue
string
expires
stringnull
mode

Response

Example request

POST /api/projects/:project_id/engineering_analytics/quarantine/request
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/engineering_analytics/quarantine/request/\
	-d operation=undefined,\
	-d selector="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/engineering_analytics/quarantine/request/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"selector": "string"
	}
).json()

Example response

Status 201 The opened pull request, plus the tracking issue for a new quarantine.

RESPONSE
{
  "pr_url": "string",
  "issue_url": "string",
  "branch": "string"
}

Status 400 Invalid input, or the write could not be completed (no GitHub App installed on the repo's org, a malformed quarantine file, or a GitHub failure). The detail message is safe to show.

Retrieve engineering analytics repo

Repo-level headline aggregates over a window (default -30d): run count, success rate, re-run cycles, merged-PR count (bots included), median PR open-to-merge (bots and drafts excluded; coarse — draft and ready time fused), and billable minutes + estimated cost — each with its equal-length previous-window twin so a caller can render honest deltas. Also carries the detected default branch and its completed-run history series (skippable via include_series=false). Cost figures are null until the job-level source is synced.

Required API key scopes

engineering_analytics:read

Query parameters

date_from
string
date_to
string
include_series
boolean
repo
string
source_id
string

Response

Example request

GET /api/projects/:project_id/engineering_analytics/repo_overview
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/repo_overview/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/engineering_analytics/repo_overview/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "cost_series": [
    {
      "bucket_start": "2019-08-24T14:15:22Z",
      "estimated_cost_usd": 0,
      "merges": 0,
      "cost_per_merge_usd": 0
    }
  ],
  "time_to_green_series": [
    {
      "bucket_start": "2019-08-24T14:15:22Z",
      "p50_seconds": 0
    }
  ],
  "success_rate_series": [
    {
      "bucket_start": "2019-08-24T14:15:22Z",
      "success_rate": 0
    }
  ],
  "open_to_merge_series": [
    {
      "bucket_start": "2019-08-24T14:15:22Z",
      "p50_seconds": 0
    }
  ],
  "run_count": 0,
  "run_count_prev": 0,
  "success_rate": 0,
  "success_rate_prev": 0,
  "rerun_cycles": 0,
  "rerun_cycles_prev": 0,
  "merged_pr_count": 0,
  "merged_pr_count_prev": 0,
  "median_open_to_merge_seconds": 0,
  "median_open_to_merge_seconds_prev": 0,
  "billable_minutes": 0,
  "billable_minutes_prev": 0,
  "estimated_cost_usd": 0,
  "estimated_cost_usd_prev": 0,
  "jobs_available": true,
  "default_branch": "string",
  "cost_series_granularity": "string",
  "time_to_green_series_granularity": "string",
  "success_rate_series_granularity": "string",
  "open_to_merge_series_granularity": "string"
}

Status 400 Invalid date_from, date_to, or source_id, or a window over 366 days.

Retrieve engineering analytics repo

Repo-level headline aggregates over a window (default -30d): run count, success rate, re-run cycles, merged-PR count (bots included), median PR open-to-merge (bots and drafts excluded; coarse — draft and ready time fused), and billable minutes + estimated cost — each with its equal-length previous-window twin so a caller can render honest deltas. Also carries the detected default branch and its completed-run history series (skippable via include_series=false). Cost figures are null until the job-level source is synced.

Required API key scopes

engineering_analytics:read

Query parameters

date_from
string
date_to
string
include_series
boolean
repo
string
source_id
string

Response

Example request

GET /api/projects/:project_id/engineering_analytics/repo_overview
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/repo_overview/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/engineering_analytics/repo_overview/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "cost_series": [
    {
      "bucket_start": "2019-08-24T14:15:22Z",
      "estimated_cost_usd": 0,
      "merges": 0,
      "cost_per_merge_usd": 0
    }
  ],
  "time_to_green_series": [
    {
      "bucket_start": "2019-08-24T14:15:22Z",
      "p50_seconds": 0
    }
  ],
  "success_rate_series": [
    {
      "bucket_start": "2019-08-24T14:15:22Z",
      "success_rate": 0
    }
  ],
  "open_to_merge_series": [
    {
      "bucket_start": "2019-08-24T14:15:22Z",
      "p50_seconds": 0
    }
  ],
  "run_count": 0,
  "run_count_prev": 0,
  "success_rate": 0,
  "success_rate_prev": 0,
  "rerun_cycles": 0,
  "rerun_cycles_prev": 0,
  "merged_pr_count": 0,
  "merged_pr_count_prev": 0,
  "median_open_to_merge_seconds": 0,
  "median_open_to_merge_seconds_prev": 0,
  "billable_minutes": 0,
  "billable_minutes_prev": 0,
  "estimated_cost_usd": 0,
  "estimated_cost_usd_prev": 0,
  "jobs_available": true,
  "default_branch": "string",
  "cost_series_granularity": "string",
  "time_to_green_series_granularity": "string",
  "success_rate_series_granularity": "string",
  "open_to_merge_series_granularity": "string"
}

Status 400 Invalid date_from, date_to, or source_id, or a window over 366 days.

Retrieve engineering analytics repo run

Default-branch health as compact chart points over a window (default -30d), newest first, for the repo-hub run-activity chart. All of a commit's workflow runs are collapsed into ONE point per commit (head SHA): its earliest workflow start, wall-clock duration until the last workflow settled (null while any is still running), and an overall conclusion that is 'failure' if any workflow decisively failed, else 'success' when at least one passed, else 'neutral'. branch overrides the detected default branch. truncated is true when more commits matched than the cap, so the chart covers only the most recent commits.

Required API key scopes

engineering_analytics:read

Query parameters

branch
string
date_from
string
date_to
string
repo
string
source_id
string

Response

Example request

GET /api/projects/:project_id/engineering_analytics/repo_run_activity
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/repo_run_activity/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/engineering_analytics/repo_run_activity/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "points": [
    {
      "run_id": 0,
      "conclusion": "string",
      "run_started_at": "2019-08-24T14:15:22Z",
      "duration_seconds": 0,
      "head_branch": "string",
      "pr_number": 0,
      "head_sha": "string"
    }
  ],
  "truncated": true,
  "limit": 0
}

Status 400 Invalid date_from, date_to, or source_id, or a window over 366 days.

Retrieve engineering analytics repo run

Default-branch health as compact chart points over a window (default -30d), newest first, for the repo-hub run-activity chart. All of a commit's workflow runs are collapsed into ONE point per commit (head SHA): its earliest workflow start, wall-clock duration until the last workflow settled (null while any is still running), and an overall conclusion that is 'failure' if any workflow decisively failed, else 'success' when at least one passed, else 'neutral'. branch overrides the detected default branch. truncated is true when more commits matched than the cap, so the chart covers only the most recent commits.

Required API key scopes

engineering_analytics:read

Query parameters

branch
string
date_from
string
date_to
string
repo
string
source_id
string

Response

Example request

GET /api/projects/:project_id/engineering_analytics/repo_run_activity
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/repo_run_activity/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/engineering_analytics/repo_run_activity/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "points": [
    {
      "run_id": 0,
      "conclusion": "string",
      "run_started_at": "2019-08-24T14:15:22Z",
      "duration_seconds": 0,
      "head_branch": "string",
      "pr_number": 0,
      "head_sha": "string"
    }
  ],
  "truncated": true,
  "limit": 0
}

Status 400 Invalid date_from, date_to, or source_id, or a window over 366 days.

Retrieve engineering analytics resolve

Resolve a git branch to the pull request(s) it belongs to — the cross-product link seam so another product (the LLM analytics UI) can turn a git branch into a PR detail link. Matches the PR's head ref, open PRs first then most recently updated. Pass timestamp (the trace's capture time) to prefer the PR that was active at that moment when a branch name has been reused across PRs. branch is required. Returns a possibly-empty, possibly-multi list — an empty list is a valid 200 (the caller renders a plain chip).

Required API key scopes

engineering_analytics:read

Query parameters

branch
string
repo
string
source_id
string
timestamp
string

Example request

GET /api/projects/:project_id/engineering_analytics/resolve_branch
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/resolve_branch/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/engineering_analytics/resolve_branch/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "repo": "string",
  "number": 0,
  "title": "string",
  "state": "string"
}

Status 400 Branch missing/empty, or invalid repo/timestamp/source_id.

Retrieve engineering analytics resolve

Resolve a git branch to the pull request(s) it belongs to — the cross-product link seam so another product (the LLM analytics UI) can turn a git branch into a PR detail link. Matches the PR's head ref, open PRs first then most recently updated. Pass timestamp (the trace's capture time) to prefer the PR that was active at that moment when a branch name has been reused across PRs. branch is required. Returns a possibly-empty, possibly-multi list — an empty list is a valid 200 (the caller renders a plain chip).

Required API key scopes

engineering_analytics:read

Query parameters

branch
string
repo
string
source_id
string
timestamp
string

Example request

GET /api/projects/:project_id/engineering_analytics/resolve_branch
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/resolve_branch/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/engineering_analytics/resolve_branch/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "repo": "string",
  "number": 0,
  "title": "string",
  "state": "string"
}

Status 400 Branch missing/empty, or invalid repo/timestamp/source_id.

Retrieve engineering analytics run failure

The thinned CI failure logs of one workflow run, grouped by failed job — the run-scoped twin of ci_failure_logs for surfaces that aren't PR-scoped (default-branch failures, the run page). logs_available is false when the run didn't fail or its logs aged out of the short Logs retention.

Required API key scopes

engineering_analytics:read

Query parameters

repo
string
run_id
integer
source_id
string

Response

Example request

GET /api/projects/:project_id/engineering_analytics/run_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/run_failure_logs/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/engineering_analytics/run_failure_logs/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "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
    }
  ],
  "run_id": 0,
  "logs_available": true,
  "truncated": true
}

Status 400 Missing or non-integer run_id, or invalid source_id.

Retrieve engineering analytics run failure

The thinned CI failure logs of one workflow run, grouped by failed job — the run-scoped twin of ci_failure_logs for surfaces that aren't PR-scoped (default-branch failures, the run page). logs_available is false when the run didn't fail or its logs aged out of the short Logs retention.

Required API key scopes

engineering_analytics:read

Query parameters

repo
string
run_id
integer
source_id
string

Response

Example request

GET /api/projects/:project_id/engineering_analytics/run_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/run_failure_logs/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/engineering_analytics/run_failure_logs/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "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
    }
  ],
  "run_id": 0,
  "logs_available": true,
  "truncated": true
}

Status 400 Missing or non-integer run_id, or invalid source_id.

← Previous pageNext page →

`GET`
`GET`
`GET`
`GET`
`GET`
`POST`
`GET`
`GET`
`GET`
`GET`

Engineering

Endpoints

Retrieve engineering analytics pr

Required API key scopes

Query parameters

Response

Example request

Example response

Status 200

Status 400 Missing pr_number/repo, or invalid repo or source_id.

Retrieve engineering analytics pr

Required API key scopes

Query parameters

Response

Example request

Example response

Status 200

Status 400 Missing pr_number/repo, or invalid repo or source_id.

Retrieve engineering analytics pr

Required API key scopes

Query parameters

Response

Example request

Example response

Status 200

Status 400 Missing pr_number/repo, or invalid repo or source_id.

Status 404 No pull request with that number in the warehouse.

Retrieve engineering analytics pr

Required API key scopes

Query parameters

Response

Example request

Example response

Status 200

Status 400 Missing pr_number/repo, or invalid repo or source_id.

Status 404 No pull request with that number in the warehouse.

Retrieve engineering analytics pr

Required API key scopes

Query parameters

Example request

Example response

Status 200

Status 400 Missing pr_number/repo, or invalid repo or source_id.

Retrieve engineering analytics pr

Required API key scopes

Query parameters

Example request

Example response

Status 200

Status 400 Missing pr_number/repo, or invalid repo or source_id.

Retrieve engineering analytics pull

Required API key scopes

Query parameters

Response

Example request

Example response

Status 200

Status 400 Invalid date_from or source_id.

Retrieve engineering analytics pull

Required API key scopes

Query parameters

Response

Example request

Example response

Status 200

Status 400 Invalid date_from or source_id.

Retrieve engineering analytics

Required API key scopes

Query parameters

Response

Example request

Example response

Status 200

Status 400 Invalid repo or source_id.

Retrieve engineering analytics

Required API key scopes

Query parameters

Response

Example request

Example response