Engineering API Reference

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, 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. 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
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,
  "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, 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. 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
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,
  "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
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
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 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

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

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

The team's connected GitHub data warehouse sources, oldest first. Populate a source picker from this and pass a chosen id back as source_id to the other endpoints. A team can connect GitHub more than once (e.g. one source per repository); this lists them all, including any whose tables aren't fully synced yet.

Required API key scopes

engineering_analytics:read

Example request

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

Example response

Status 200

RESPONSE
{
  "id": "string",
  "repo": "string",
  "prefix": "string"
}

Retrieve engineering analytics

The team's connected GitHub data warehouse sources, oldest first. Populate a source picker from this and pass a chosen id back as source_id to the other endpoints. A team can connect GitHub more than once (e.g. one source per repository); this lists them all, including any whose tables aren't fully synced yet.

Required API key scopes

engineering_analytics:read

Example request

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

Example response

Status 200

RESPONSE
{
  "id": "string",
  "repo": "string",
  "prefix": "string"
}

Retrieve engineering analytics workflow

Per-workflow CI health over a window (default last 24 hours, maximum 366 days): run count, success rate, p50/p95 duration, last failure time, latest-run status, and a zero-filled run history bucketed by hour/day/week to fit the window. p50/p95 are over successful runs only, so cancelled (superseded) and failed runs never bias the duration trend. Optionally scope to a single git branch via branch, or to attributed pull-request runs via run_scope=pull_request. Use this for 'is CI getting slower' and 'which workflow is the long pole'; compare two windows to get a trend.

Required API key scopes

engineering_analytics:read

Query parameters

branch
string
date_from
string
date_to
string
run_scope
string
One of: "all""pull_request"
source_id
string

Example request

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

Example response

Status 200

RESPONSE
{
  "repo": {
    "provider": "string",
    "owner": "string",
    "name": "string"
  },
  "buckets": [
    {
      "bucket_start": "2019-08-24T14:15:22Z",
      "run_count": 0,
      "completed": 0,
      "successes": 0,
      "failures": 0
    }
  ],
  "workflow_name": "string",
  "run_count": 0,
  "success_rate": 0,
  "p50_seconds": 0,
  "p95_seconds": 0,
  "last_failure_at": "2019-08-24T14:15:22Z",
  "latest_run_failed": true,
  "latest_run_conclusion": "string",
  "granularity": "string",
  "billable_minutes": 0,
  "estimated_cost_usd": 0,
  "rerun_cycles": 0,
  "success_rate_prev": 0
}

Status 400 Invalid date_from, date_to, run_scope, or source_id, or a window longer than 366 days.

Retrieve engineering analytics workflow

Per-workflow CI health over a window (default last 24 hours, maximum 366 days): run count, success rate, p50/p95 duration, last failure time, latest-run status, and a zero-filled run history bucketed by hour/day/week to fit the window. p50/p95 are over successful runs only, so cancelled (superseded) and failed runs never bias the duration trend. Optionally scope to a single git branch via branch, or to attributed pull-request runs via run_scope=pull_request. Use this for 'is CI getting slower' and 'which workflow is the long pole'; compare two windows to get a trend.

Required API key scopes

engineering_analytics:read

Query parameters

branch
string
date_from
string
date_to
string
run_scope
string
One of: "all""pull_request"
source_id
string

Example request

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

Example response

Status 200

RESPONSE
{
  "repo": {
    "provider": "string",
    "owner": "string",
    "name": "string"
  },
  "buckets": [
    {
      "bucket_start": "2019-08-24T14:15:22Z",
      "run_count": 0,
      "completed": 0,
      "successes": 0,
      "failures": 0
    }
  ],
  "workflow_name": "string",
  "run_count": 0,
  "success_rate": 0,
  "p50_seconds": 0,
  "p95_seconds": 0,
  "last_failure_at": "2019-08-24T14:15:22Z",
  "latest_run_failed": true,
  "latest_run_conclusion": "string",
  "granularity": "string",
  "billable_minutes": 0,
  "estimated_cost_usd": 0,
  "rerun_cycles": 0,
  "success_rate_prev": 0
}

Status 400 Invalid date_from, date_to, run_scope, or source_id, or a window longer than 366 days.

Retrieve engineering analytics workflow

Jobs of a single workflow run attempt, with per-job duration, runner tier, and estimated cost. Scoped to one run_attempt (the latest unless specified) so a re-run's attempts don't merge. Returns an empty list when the job-level source isn't synced yet.

Required API key scopes

engineering_analytics:read

Query parameters

run_attempt
integer
run_id
integer
source_id
string

Example request

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

Example response

Status 200

RESPONSE
{
  "id": 0,
  "run_id": 0,
  "name": "string",
  "status": "string",
  "conclusion": "string",
  "started_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "duration_seconds": 0,
  "runner_provider": "string",
  "runner_label": "string",
  "estimated_cost_usd": 0
}

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

Retrieve engineering analytics workflow

Jobs of a single workflow run attempt, with per-job duration, runner tier, and estimated cost. Scoped to one run_attempt (the latest unless specified) so a re-run's attempts don't merge. Returns an empty list when the job-level source isn't synced yet.

Required API key scopes

engineering_analytics:read

Query parameters

run_attempt
integer
run_id
integer
source_id
string

Example request

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

Example response

Status 200

RESPONSE
{
  "id": 0,
  "run_id": 0,
  "name": "string",
  "status": "string",
  "conclusion": "string",
  "started_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "duration_seconds": 0,
  "runner_provider": "string",
  "runner_label": "string",
  "estimated_cost_usd": 0
}

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

Retrieve engineering analytics workflow

A single workflow run: status, conclusion, duration, branch, attempt, and the attributed pull request. Run-level only — per-job and per-step detail are not tracked yet.

Required API key scopes

engineering_analytics:read

Query parameters

run_id
integer
source_id
string

Response

Example request

GET /api/projects/:project_id/engineering_analytics/workflow_run
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/workflow_run/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/engineering_analytics/workflow_run/".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 or non-integer run_id, or invalid source_id.

Status 404 No workflow run with that id in the warehouse.

Retrieve engineering analytics workflow

A single workflow run: status, conclusion, duration, branch, attempt, and the attributed pull request. Run-level only — per-job and per-step detail are not tracked yet.

Required API key scopes

engineering_analytics:read

Query parameters

run_id
integer
source_id
string

Response

Example request

GET /api/projects/:project_id/engineering_analytics/workflow_run
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/workflow_run/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/engineering_analytics/workflow_run/".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 or non-integer run_id, or invalid source_id.

Status 404 No workflow run with that id in the warehouse.

Retrieve engineering analytics workflow run

Compact per-run points for a single workflow over a window (date_from default -30d), newest first, for the run-activity chart: each run's start time, duration, conclusion, branch, and attributed PR. Optionally scope to a single git branch via branch, matching workflow_runs. Leaner and higher-capped than workflow_runs so the chart spans the full window even on busy workflows; truncated is true when the cap is hit, so the chart covers only the most recent runs.

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

Response

Example request

GET /api/projects/:project_id/engineering_analytics/workflow_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/workflow_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/workflow_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 Missing workflow_name/repo, or invalid date or source_id.

Retrieve engineering analytics workflow run

Compact per-run points for a single workflow over a window (date_from default -30d), newest first, for the run-activity chart: each run's start time, duration, conclusion, branch, and attributed PR. Optionally scope to a single git branch via branch, matching workflow_runs. Leaner and higher-capped than workflow_runs so the chart spans the full window even on busy workflows; truncated is true when the cap is hit, so the chart covers only the most recent runs.

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

Response

Example request

GET /api/projects/:project_id/engineering_analytics/workflow_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/workflow_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/workflow_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 Missing workflow_name/repo, or invalid date or source_id.

← Previous pageNext page →

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

Engineering

Endpoints

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

Status 200

Status 400 Invalid repo or source_id.

Create engineering analytics quarantine

Required API key scopes

Request parameters

Response

Example request

Example response

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

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

Required API key scopes

Request parameters

Response

Example request

Example response

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

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

Required API key scopes

Query parameters

Response

Example request

Example response

Status 200

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

Retrieve engineering analytics repo

Required API key scopes

Query parameters

Response

Example request

Example response

Status 200

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

Retrieve engineering analytics repo run

Required API key scopes

Query parameters

Response

Example request

Example response

Status 200

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

Retrieve engineering analytics repo run

Required API key scopes

Query parameters

Response

Example request

Example response

Status 200

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

Retrieve engineering analytics run failure

Required API key scopes

Query parameters

Response

Example request

Example response

Status 200

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

Retrieve engineering analytics run failure

Required API key scopes

Query parameters

Response

Example request

Example response