Live Debugger

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

Create, Read, Update and Delete breakpoints for live debugging.

Endpoints

GET
POST
GET
PATCH
DELETE
GET
GET

List all live debugger breakpoints

Required API key scopes

live_debugger:read

Path parameters

  • project_id
    string

    Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

  • filename
    string
  • limit
    integer

    Number of results to return per page.

  • offset
    integer

    The initial index from which to return the results.

  • repository
    string

Response


Example request

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

Example response

Status 200
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "repository": "string",
      "filename": "string",
      "line_number": 2147483647,
      "enabled": true,
      "condition": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Create live debugger breakpoints

Required API key scopes

live_debugger:write

Path parameters

  • project_id
    string

    Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Request parameters

  • repository
    string
  • filename
    string
  • line_number
    integer
  • enabled
    boolean
  • condition
    string

Response


Example request

POST /api/projects/:project_id/live_debugger_breakpoints
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/live_debugger_breakpoints/\
	-d filename="string",\
	-d line_number="integer"

Example response

Status 201
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "repository": "string",
  "filename": "string",
  "line_number": 2147483647,
  "enabled": true,
  "condition": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Retrieve live debugger breakpoints

Required API key scopes

live_debugger:read

Path parameters

  • id
    string

    A UUID string identifying this live debugger breakpoint.

  • project_id
    string

    Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Response


Example request

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

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "repository": "string",
  "filename": "string",
  "line_number": 2147483647,
  "enabled": true,
  "condition": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Update live debugger breakpoints

Required API key scopes

live_debugger:write

Path parameters

  • id
    string

    A UUID string identifying this live debugger breakpoint.

  • project_id
    string

    Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Request parameters

  • repository
    string
  • filename
    string
  • line_number
    integer
  • enabled
    boolean
  • condition
    string

Response


Example request

PATCH /api/projects/:project_id/live_debugger_breakpoints/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/live_debugger_breakpoints/:id/\
	-d repository="string"

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "repository": "string",
  "filename": "string",
  "line_number": 2147483647,
  "enabled": true,
  "condition": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Delete live debugger breakpoints

Required API key scopes

live_debugger:write

Path parameters

  • id
    string

    A UUID string identifying this live debugger breakpoint.

  • project_id
    string

    Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Example request

DELETE /api/projects/:project_id/live_debugger_breakpoints/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/live_debugger_breakpoints/:id/

Example response

Status 204 No response body

Retrieve live debugger breakpoints active

External API endpoint for client applications to fetch active breakpoints using Project API key. This endpoint allows external client applications (like Python scripts, Node.js apps, etc.) to fetch the list of active breakpoints so they can instrument their code accordingly.

Authentication: Requires a Project API Key in the Authorization header: Authorization: Bearer phs_<your-project-api-key>. You can find your Project API Key in PostHog at: Settings → Project → Project API Key

Required API key scopes

live_debugger:read

Path parameters

  • project_id
    string

    Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

  • enabled
    boolean

    Only return enabled breakpoints

  • filename
    string

    Filter breakpoints for a specific file

  • repository
    string

    Filter breakpoints for a specific repository (e.g., 'PostHog/posthog')

Response


Example request

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

Example response

Status 200 List of breakpoints for client consumption
RESPONSE
{
  "breakpoints": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "repository": "string",
      "filename": "string",
      "line_number": 0,
      "enabled": true,
      "condition": "string"
    }
  ]
}
Status 400 Invalid query parameters
Status 401 Invalid or missing Project API key

Retrieve live debugger breakpoints breakpoint hits

Retrieve breakpoint hit events from ClickHouse with optional filtering and pagination. Returns hit events containing stack traces, local variables, and execution context from your application's runtime.

Security: Breakpoint IDs are filtered to only include those belonging to the current team.

Required API key scopes

live_debugger:read

Path parameters

  • project_id
    string

    Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

  • breakpoint_ids
    string

    Filter hits for specific breakpoints (repeat parameter for multiple IDs, e.g., ?breakpoint_ids=uuid1&breakpoint_ids=uuid2)

  • limit
    integer

    Number of hits to return (default: 100, max: 1000)

  • offset
    integer

    Pagination offset for retrieving additional results (default: 0)

Response


Example request

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

Example response

Status 200 List of breakpoint hits with pagination info
RESPONSE
{
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "lineNumber": 0,
      "functionName": "string",
      "timestamp": "2019-08-24T14:15:22Z",
      "variables": {
        "property1": null,
        "property2": null
      },
      "stackTrace": [
        null
      ],
      "breakpoint_id": "737a09c2-f16c-4c97-8532-daeb18cf5329",
      "filename": "string"
    }
  ],
  "count": 0,
  "has_more": true
}
Status 400 Invalid query parameters (invalid UUID, limit out of range, etc.)

Community questions

Questions about this page? or post a community question.