AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

querying-posthog-data

Explains how to query PostHog data, defaulting to typed runners for supported product analytics. Read it before you write HogQL/SQL. Also read it before you call execute-sql against PostHog. Use it to find or aggregate PostHog entities. These entities include insights, dashboards, cohorts, feature flags, experiments, surveys, hog flows, warehouse data, and persons. Use it for trends, funnels, retention, lifecycle, paths, stickiness, web analytics, error tracking, logs, sessions, and LLM traces. Before you calculate a governed business or telemetry measure, check system.information_schema.metrics for an approved definition. Examples include MRR, activation, billable usage, active organizations, and failure rates. Use the approved definition before you derive a measure from raw events or use a typed domain tool. It also covers HogQL differences, system table schemas, functions, query examples, and schema discovery.

Original source
posthog
License
MIT
Pinned revision
cac7c80a9e5b73484d18eda1bffb47297c938e0c

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read posthog--querying-posthog-data at revision cac7c80a9e5b73484d18eda1bffb47297c938e0c, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 65

references/models-error-tracking.md

Error Tracking

ErrorTrackingIssue (system.error_tracking_issues)

Error tracking issues represent grouped exceptions captured by PostHog SDKs. Each issue aggregates multiple exception events that share the same fingerprint.

Columns

Column | Type | Nullable | Description --- | --- | --- | --- id | String | NOT NULL | Issue UUID. team_id | Integer | NOT NULL | created_at | DateTime | NOT NULL | When the issue was first created. status | String | NOT NULL | Issue status, e.g. 'active', 'resolved', 'suppressed'. severity | String | NULL | Assigned issue severity, or null when unassigned. name | String | NOT NULL | Issue title (usually the exception type/message). description | String | NOT NULL | Issue description.

Status Values

Status | Description active | Issue is currently active and being tracked archived | Issue has been archived (hidden from default views) resolved | Issue has been marked as resolved pending_release | Issue is pending verification in a new release suppressed | Issue has been suppressed from alerts and notifications

Key Relationships

  • Fingerprints: Issues are linked to fingerprints (not queryable via HogQL)
  • Cohorts: Issues can be linked to cohorts via system.cohorts
  • Exception Events: Query via events table with event = '$exception' and issue_id

Important Notes

  • Issues group exception events by fingerprint (a hash of exception characteristics)
  • The name field is typically auto-populated from the first exception's type/message
  • Use the events table with event = '$exception' and issue_id to query actual exception occurrences
  • Use system.error_tracking_issues for all-time issue counts by status or severity
  • Access to system.error_tracking_issues follows the connected user's Error tracking permissions and only returns rows from the current project
  • Use posthog:query-error-tracking-issues-list for issues observed during a date range or for impact counts
  • Issues can be merged (combining fingerprints) or split (separating fingerprints into new issues)

ErrorTrackingSymbolSet (system.error_tracking_symbol_sets)

Symbol sets represent uploaded source maps used to unminify JavaScript stack frames. Rows can also track missing symbol sets so future uploads know which stack frames may need reprocessing.

Columns

Column | Type | Nullable | Description --- | --- | --- | --- id | String | NOT NULL | Symbol set UUID. team_id | Integer | NOT NULL | ref | String | NOT NULL | Reference identifying the symbol set, e.g. a chunk/file id. release_id | String | NULL | Release this symbol set belongs to; joins to error_tracking_releases.id. created_at | DateTime | NOT NULL | When the symbol set was uploaded. last_used | DateTime | NULL | When the symbol set was last used to symbolicate. failure_reason | String | NULL | Why symbolication with this set failed, if applicable.

Important Notes

  • Internal storage pointers and content hashes are intentionally omitted from HogQL.
  • Use posthog:error-tracking-symbol-sets-list with status = 'valid' or status = 'invalid' to check upload availability.
  • Use posthog:error-tracking-symbol-sets-list with an exact ref to resolve a reference to an ID, then posthog:error-tracking-symbol-sets-retrieve or posthog:error-tracking-symbol-sets-download-retrieve by ID. Download URLs expire after one hour; use them immediately and do not echo them back unless the user explicitly asks.

Common Query Patterns

Find symbol set lookup failures:

SELECT id, ref, failure_reason, created_at, last_used
FROM system.error_tracking_symbol_sets
WHERE failure_reason IS NOT NULL
ORDER BY created_at DESC
LIMIT 20

Find symbol set metadata by reference:

SELECT id, ref, release_id, created_at, last_used, failure_reason
FROM system.error_tracking_symbol_sets
WHERE ref = 'https://example.com/static/app.min.js'
LIMIT 1

Find issues by status:

SELECT id, name, status, created_at
FROM system.error_tracking_issues
WHERE status = 'active'
ORDER BY created_at DESC
LIMIT 20

Find issues by name pattern:

SELECT id, name, description, status
FROM system.error_tracking_issues
WHERE name ILIKE '%timeout%'
  AND status != 'archived'

Count issues by status:

SELECT status, count() AS count
FROM system.error_tracking_issues
GROUP BY status
ORDER BY count DESC

Count issues by severity:

SELECT severity, count() AS count
FROM system.error_tracking_issues
WHERE severity IS NOT NULL
GROUP BY severity
ORDER BY count DESC

Find exception events for a specific issue:

SELECT
    timestamp,
    properties.$exception_types[1] AS exception_type,
    properties.$exception_values[1] AS exception_message,
    properties.$exception_sources[1] AS source,
    person.id AS user_id
FROM events
WHERE event = '$exception'
  AND issue_id = '01234567-89ab-cdef-0123-456789abcdef'
  AND timestamp >= now() - INTERVAL 7 DAY
ORDER BY timestamp DESC
LIMIT 50

Aggregate exception stats by issue:

SELECT
    issue_id,
    count() AS occurrences,
    count(DISTINCT person.id) AS affected_users,
    min(timestamp) AS first_seen,
    max(timestamp) AS last_seen
FROM events
WHERE event = '$exception'
  AND isNotNull(issue_id)
  AND timestamp >= now() - INTERVAL 7 DAY
GROUP BY issue_id
ORDER BY occurrences DESC
LIMIT 20

Join issues with exception events:

SELECT
    i.id,
    i.name,
    i.status
FROM system.error_tracking_issues AS i
WHERE i.status = 'active'
  AND i.id IN (
    SELECT DISTINCT issue_id
    FROM events
    WHERE event = '$exception'
      AND timestamp >= now() - INTERVAL 1 DAY
  )
ORDER BY i.created_at DESC