Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

24.2 KB
Raw Blame
/**
 * Auto-generated from the Django backend OpenAPI schema.
 * MCP service uses these Zod schemas for generated tool handlers.
 * To regenerate: hogli build:openapi
 *
 * PostHog API - MCP 12 enabled ops
 * OpenAPI spec version: 1.0.0
 */
import * as zod from 'zod'

/**
 * 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, blocking the merge queue, a new failure spreading across branches, probably-resolved, flaky, or one PR's own problem: ranked with the most urgent first. A blocking_merge_queue row is a failure on a merge-queue gate branch that never hit trunk: the commit had already passed the PR's own CI, so it is the semantic conflict the queue exists to catch, and it is holding up landings. 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.
 */
export const EngineeringAnalyticsBrokenTestsParams = () => zod.object({
    project_id: zod
        .string()
        .describe(
            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
        ),
})

export const EngineeringAnalyticsBrokenTestsQueryParams = () => zod.object({
    branch: zod
        .string()
        .optional()
        .describe(
            'Optional exact branch name. Keeps only tests that failed on it, but the counts still cover every branch, so a row shows whether the test also fails elsewhere. Applied before the limit.'
        ),
    repo: zod
        .string()
        .optional()
        .describe(
            "'owner\/name' repository to scope to when the selected source syncs several repositories (from the `sources` list). Defaults to the source's first repository."
        ),
    source_id: zod
        .string()
        .optional()
        .describe(
            'Connected GitHub data warehouse source to read from. Defaults to the oldest connected GitHub source that the `sources` list reports as synced, when the team has more than one.'
        ),
    test: zod
        .string()
        .optional()
        .describe(
            "Optional case-insensitive substring of the test id to keep, e.g. 'test_cohort' or 'posthog\/api\/test\/test_user.py'. Applied before the limit, so a test past the cap is still found."
        ),
})

/**
 * 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.
 */
export const EngineeringAnalyticsCiFailureLogsParams = () => zod.object({
    project_id: zod
        .string()
        .describe(
            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
        ),
})

export const EngineeringAnalyticsCiFailureLogsQueryParams = () => zod.object({
    pr_number: zod.number().describe('Pull request number whose CI failure logs to fetch.'),
    repo: zod.string().describe("'owner\/name' repository the pull request belongs to."),
    source_id: zod
        .string()
        .optional()
        .describe(
            'Connected GitHub data warehouse source to read from. Defaults to the oldest connected GitHub source that the `sources` list reports as synced, when the team has more than one.'
        ),
})

/**
 * The active test-health queue: pytest and Jest 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 a tolerated failure is recorded while it is masked; otherwise 'suspected_regression'. It qualifies on any same-commit recovery, any master/main failure, a quarantined failure, or failures on at least min_failed_prs distinct PRs. Counts are absolute, never rates: CI emits every failure but omits ordinary passing spans, so there is no execution denominator. 'suspected_regression' means no recovery was recorded in this data, not that the test never flakes.
 */
export const EngineeringAnalyticsFlakyTestsParams = () => zod.object({
    project_id: zod
        .string()
        .describe(
            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
        ),
})

export const EngineeringAnalyticsFlakyTestsQueryParams = () => zod.object({
    branch: zod
        .string()
        .optional()
        .describe(
            'Optional exact branch name. Keeps only tests that failed on it, but the counts still cover every branch, so a row shows whether the test also fails elsewhere. Applied before the limit.'
        ),
    date_from: zod
        .string()
        .optional()
        .describe(
            "Window start: relative ('-7d', '-30d') or ISO8601. Defaults to -7d; the window may span at most 30 days."
        ),
    date_to: zod.string().optional().describe('Window end: relative or ISO8601. Defaults to now.'),
    limit: zod.number().optional().describe('Maximum number of tests to return (1-200). Defaults to 50.'),
    min_failed_prs: zod
        .number()
        .optional()
        .describe(
            'A test with no recorded recovery qualifies once it failed on at least this many distinct pull requests in the window. Minimum 1. Defaults to 3.'
        ),
    pr_number: zod
        .number()
        .optional()
        .describe(
            "Optional pull request number. Keeps only tests that failed in that PR's CI runs, but the counts still cover every PR. Pass min_failed_prs=1 too, so a test that failed on this PR alone qualifies. Applied before the limit."
        ),
    repo: zod
        .string()
        .optional()
        .describe(
            "'owner\/name' repository to scope to when the selected source syncs several repositories (from the `sources` list). Defaults to the source's first repository."
        ),
    runner: zod.enum(['jest', 'pytest']).optional().describe("Optional test runner to return: 'pytest' or 'jest'."),
    source_id: zod
        .string()
        .optional()
        .describe(
            'Connected GitHub data warehouse source to read from. Defaults to the oldest connected GitHub source that the `sources` list reports as synced, when the team has more than one.'
        ),
    test: zod
        .string()
        .optional()
        .describe(
            "Optional case-insensitive substring of the test id to keep, e.g. 'test_cohort' or 'posthog\/api\/test\/test_user.py'. Applied before the limit, so a test past the cap is still found."
        ),
})

/**
 * 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.
 */
export const EngineeringAnalyticsPrCostParams = () => zod.object({
    project_id: zod
        .string()
        .describe(
            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
        ),
})

export const EngineeringAnalyticsPrCostQueryParams = () => zod.object({
    pr_number: zod.number().describe('Pull request number to estimate cost for.'),
    repo: zod.string().describe("'owner\/name' repository the pull request belongs to."),
    source_id: zod
        .string()
        .optional()
        .describe(
            'Connected GitHub data warehouse source to read from. Defaults to the oldest connected GitHub source that the `sources` list reports as synced, when the team has more than one.'
        ),
})

/**
 * 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.
 */
export const EngineeringAnalyticsPrLifecycleParams = () => zod.object({
    project_id: zod
        .string()
        .describe(
            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
        ),
})

export const EngineeringAnalyticsPrLifecycleQueryParams = () => zod.object({
    pr_number: zod.number().describe('Pull request number to inspect.'),
    repo: zod.string().describe("'owner\/name' repository the pull request belongs to."),
    source_id: zod
        .string()
        .optional()
        .describe(
            'Connected GitHub data warehouse source to read from. Defaults to the oldest connected GitHub source that the `sources` list reports as synced, when the team has more than one.'
        ),
})

/**
 * Open pull requests plus any merged or closed since date_from (default -30d), newest first, each with its head-SHA CI rollup. Pass state to list one state only. The list is paged by limit and offset; 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. Cost and billable minutes can lag new CI by up to 5 minutes.
 */
export const EngineeringAnalyticsPullRequestsParams = () => zod.object({
    project_id: zod
        .string()
        .describe(
            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
        ),
})

export const EngineeringAnalyticsPullRequestsQueryParams = () => zod.object({
    author: zod.string().optional().describe("Optional GitHub login to scope the list to one author's pull requests."),
    date_from: zod.string().optional().describe("Window start: relative ('-30d', '-8w') or ISO8601. Defaults to -30d."),
    date_to: zod
        .string()
        .optional()
        .describe(
            'Optional exclusive upper bound for merged_at \/ closed_at: relative or ISO8601. Defaults to now. Set a fixed value when you page, so new merges do not move rows between pages.'
        ),
    limit: zod.number().optional().describe('Page size, 1 to 1000. Defaults to 1000.'),
    offset: zod
        .number()
        .optional()
        .describe(
            'Number of rows to skip. Defaults to 0. While `truncated` is true, add `limit` to offset to read the next page.'
        ),
    repo: zod
        .string()
        .optional()
        .describe(
            "'owner\/name' repository to scope to when the selected source syncs several repositories (from the `sources` list). Defaults to the source's first repository."
        ),
    source_id: zod
        .string()
        .optional()
        .describe(
            'Connected GitHub data warehouse source to read from. Defaults to the oldest connected GitHub source that the `sources` list reports as synced, when the team has more than one.'
        ),
    state: zod
        .enum(['closed', 'merged', 'open'])
        .optional()
        .describe(
            "Optional state filter. 'merged' lists PRs merged in the window, newest merged_at first. 'closed' lists PRs closed without a merge in the window, newest closed_at first. 'open' lists all open PRs whatever their age, newest first. Omit it to get open PRs plus any merged or closed in the window."
        ),
})

/**
 * 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.
 */
export const EngineeringAnalyticsRunFailureLogsParams = () => zod.object({
    project_id: zod
        .string()
        .describe(
            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
        ),
})

export const EngineeringAnalyticsRunFailureLogsQueryParams = () => zod.object({
    ci_engine: zod
        .enum(['depot_ci', 'github_actions'])
        .optional()
        .describe('CI engine. Required when run_id exists in both engines.'),
    repo: zod
        .string()
        .optional()
        .describe(
            "'owner\/name' repository to scope to when the selected source syncs several repositories (from the `sources` list). Defaults to the source's first repository."
        ),
    run_id: zod.number().describe('Workflow run id whose failure logs to fetch.'),
    source_id: zod
        .string()
        .optional()
        .describe(
            'Connected GitHub data warehouse source to read from. Defaults to the oldest connected GitHub source that the `sources` list reports as synced, when the team has more than one.'
        ),
})

/**
 * The team's selectable GitHub repositories, oldest source first: one entry per repository a source is configured to sync, so a source syncing several repositories appears once per repo. Populate a repo picker from this and pass a chosen entry's `id` back as `source_id` and its `repo` back as `repo` to the other endpoints. Includes repositories whose tables aren't fully synced yet.
 */
export const EngineeringAnalyticsSourcesParams = () => zod.object({
    project_id: zod
        .string()
        .describe(
            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
        ),
})

/**
 * Per-owning-team rollup of the CI test surfaces each team owns, over the same run evidence as flaky_tests and with the same meaning of flaky: flaky_test_count is owned tests one commit was seen both failing and passing in the window, regression_test_count is owned tests that failed with no such proof and still hit the blast-radius bar, plus failed/recovery/quarantined run counts. Each has an equal-length previous-window twin for honest deltas. Ownership is stamped on the spans at CI emission time from the repo's ownership map (the distributed owners.yaml files); unstamped spans aggregate under the literal team 'unowned', and a re-stamped test lands under its latest owner only. Each row also carries test_file_count (the daily owners.yaml census denominator, with a window-start twin) and merged_pr_count (merged PRs by the team's members, bots excluded); teams with census counts but no CI signal appear with zero signal counts and a null last_seen_at. Teams are organizational owners of code surfaces, never authors. Counts are absolute, never rates: CI emits every failure but omits ordinary passing spans, so there is no execution denominator. 'suspected_regression' means no recovery was recorded in this data, not that the test never flakes.
 */
export const EngineeringAnalyticsTeamCiHealthParams = () => zod.object({
    project_id: zod
        .string()
        .describe(
            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
        ),
})

export const EngineeringAnalyticsTeamCiHealthQueryParams = () => zod.object({
    date_from: zod
        .string()
        .optional()
        .describe(
            "Window start: relative ('-14d', '-7d') or ISO8601. Defaults to -14d; the window may span at most 30 days. An equal-length prior window is scanned for the \*_prior twins; near the 30-day ceiling that prior window can reach past Traces retention, deflating \*_prior counts and overstating deltas."
        ),
    date_to: zod.string().optional().describe('Window end: relative or ISO8601. Defaults to now.'),
    limit: zod.number().optional().describe('Maximum number of teams to return (1-200). Defaults to 100.'),
    min_failed_prs: zod
        .number()
        .optional()
        .describe(
            'An unrecovered test counts toward regression_test_count once it failed on at least this many distinct pull requests in the window. Minimum 1. Defaults to 3. Does not affect flaky_test_count, which needs proof, not a threshold.'
        ),
    owner_team: zod
        .string()
        .optional()
        .describe(
            "Restrict the roster to one owning team slug (or 'unowned'). The cheap way to read a single team's rollup."
        ),
    repo: zod
        .string()
        .optional()
        .describe(
            "'owner\/name' repository to scope to when the selected source syncs several repositories (from the `sources` list). Defaults to the source's first repository."
        ),
    source_id: zod
        .string()
        .optional()
        .describe(
            'Connected GitHub data warehouse source to read from. Defaults to the oldest connected GitHub source that the `sources` list reports as synced, when the team has more than one.'
        ),
})

/**
 * 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. Success rate covers runs that succeeded or ended in a decisive failure. Skipped, cancelled, neutral, and action-required runs are excluded. p50/p95 are over successful runs only, so cancelled (superseded) and failed runs never bias the duration trend. Runs under 10 seconds that did no work are excluded when longer successful runs exist. An all-fast workflow uses every successful run. Optionally scope to a single git branch via `branch`, to one workflow via `workflow_name`, or to one run group via `run_scope` (default_branch, pull_request, merge_queue). Use this for 'is CI getting slower' and 'which workflow is the long pole'; compare two windows to get a trend.
 */
export const EngineeringAnalyticsWorkflowHealthParams = () => zod.object({
    project_id: zod
        .string()
        .describe(
            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
        ),
})

export const EngineeringAnalyticsWorkflowHealthQueryParams = () => zod.object({
    branch: zod
        .string()
        .optional()
        .describe(
            "Optional exact git branch (head_branch) to scope results to, e.g. 'main'. Omit or leave blank to aggregate across all branches."
        ),
    date_from: zod.string().optional().describe("Window start: relative ('-24h', '-7d') or ISO8601. Defaults to -24h."),
    date_to: zod.string().optional().describe('Window end: relative or ISO8601. Defaults to now.'),
    repo: zod
        .string()
        .optional()
        .describe(
            "'owner\/name' repository to scope to when the selected source syncs several repositories (from the `sources` list). Defaults to the source's first repository."
        ),
    run_scope: zod
        .enum(['all', 'default_branch', 'merge_queue', 'pull_request'])
        .optional()
        .describe(
            "Which group of runs to report on: 'all' (default) is every run; 'default_branch' is runs on master or main; 'pull_request' is runs on PR branches, excluding default-branch and merge-queue runs; 'merge_queue' is the gate runs the merge queue fired before a merge landed. Fork PRs carry no PR attribution (a GitHub limitation), so they appear only under 'all'. Any other value is a 400."
        ),
    source_id: zod
        .string()
        .optional()
        .describe(
            'Connected GitHub data warehouse source to read from. Defaults to the oldest connected GitHub source that the `sources` list reports as synced, when the team has more than one.'
        ),
    workflow_name: zod
        .string()
        .optional()
        .describe(
            "Optional exact workflow name to scope results to, e.g. 'Backend CI'. Omit to rank every workflow. Pass it when you want one workflow's figures over the whole window rather than the top slice."
        ),
})

/**
 * 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.
 */
export const EngineeringAnalyticsWorkflowJobsParams = () => zod.object({
    project_id: zod
        .string()
        .describe(
            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
        ),
})

export const EngineeringAnalyticsWorkflowJobsQueryParams = () => zod.object({
    ci_engine: zod
        .enum(['depot_ci', 'github_actions'])
        .optional()
        .describe('CI engine. Required when run_id exists in both engines.'),
    repo: zod
        .string()
        .optional()
        .describe(
            "'owner\/name' repository to scope to when the selected source syncs several repositories (from the `sources` list). Defaults to the source's first repository."
        ),
    run_attempt: zod
        .number()
        .optional()
        .describe(
            "Which re-run attempt to scope jobs to. Omit to use the run's latest attempt; pass an explicit attempt to avoid mixing jobs across a re-run's attempts."
        ),
    run_id: zod.number().describe('Workflow run id to list jobs for.'),
    source_id: zod
        .string()
        .optional()
        .describe(
            'Connected GitHub data warehouse source to read from. Defaults to the oldest connected GitHub source that the `sources` list reports as synced, when the team has more than one.'
        ),
})

/**
 * A workflow's estimated CI cost broken down by runner tier over a window (date_from default -30d), highest spend first. Optionally scope to a single git branch via `branch` or one run group via `run_scope`. Returns an empty list when the job-level source isn't synced.
 */
export const EngineeringAnalyticsWorkflowRunnerCostsParams = () => zod.object({
    project_id: zod
        .string()
        .describe(
            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
        ),
})

export const EngineeringAnalyticsWorkflowRunnerCostsQueryParams = () => zod.object({
    branch: zod
        .string()
        .optional()
        .describe(
            "Optional exact git branch (head_branch) to scope results to, e.g. 'main'. Omit or leave blank to aggregate across all branches."
        ),
    date_from: zod.string().optional().describe("Window start: relative ('-30d', '-8w') or ISO8601. Defaults to -30d."),
    date_to: zod.string().optional().describe('Window end: relative or ISO8601. Defaults to now.'),
    repo: zod.string().describe("'owner\/name' repository the workflow belongs to."),
    run_scope: zod
        .enum(['all', 'default_branch', 'merge_queue', 'pull_request'])
        .optional()
        .describe(
            "Which group of runs to report on: 'all' (default) is every run; 'default_branch' is runs on master or main; 'pull_request' is runs on PR branches, excluding default-branch and merge-queue runs; 'merge_queue' is the gate runs the merge queue fired before a merge landed. Fork PRs carry no PR attribution (a GitHub limitation), so they appear only under 'all'. Any other value is a 400."
        ),
    source_id: zod
        .string()
        .optional()
        .describe(
            'Connected GitHub data warehouse source to read from. Defaults to the oldest connected GitHub source that the `sources` list reports as synced, when the team has more than one.'
        ),
    workflow_name: zod.string().describe('Workflow name to break down cost for.'),
})