Skip to main content
skill CX Codex

exploring-endpoint-execution-logs — Claude Code skill: setup

exploring-endpoint-execution-logs inspects execution records for a single PostHog endpoint to troubleshoot errors, cache misses, and zero-row outputs. Useful when an API query fails.

MIT 318 installs ★ 80 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add PostHog/skills --skill exploring-endpoint-execution-logs -a claude-code
Open on GitHub

What exploring-endpoint-execution-logs does

Every endpoint invocation writes a single line to the PostHog log_entries store. This skill fetches those records to pinpoint run failures, cache behavior, and returned row counts. Each entry carries structured key=value tokens, detailing the runtime path (materialized, inline, or ducklake), duration, schema version, and specific error classes like ResolutionError or HogVMException.

The workflow relies on endpoint-logs to query messages, set time boundaries, and inspect up to 500 records. For broader trends, the agent combines endpoint UUID data from endpoint-get with aggregate SQL queries over log_entries.

Because log_entries enforces a TTL around 90 days, older runs cannot be retrieved. Logging operates on a best-effort basis without blocking query execution. If a run succeeds on the client side but drops from the feed, only the log write failed, not the underlying query. Step traces are absent: one run creates one summary line.

What it helps with

  • Pinpoint runtime failures such as ResolutionError on a PostHog endpoint
  • Verify whether recent endpoint invocations hit cache
  • Detect row count drops across different endpoint versions
  • Calculate weekly error rates using direct SQL aggregation on log_entries

Example prompts for the agent

  • Show recent ERROR logs for the weekly_signups endpoint
  • Did the last run of endpoint revenue_metrics hit cache or inline execution?
  • Check if endpoint active_users returned any rows this morning

How to install exploring-endpoint-execution-logs

1Skills CLI (Vercel)

npx skills add PostHog/skills --skill exploring-endpoint-execution-logs -a claude-code

2Manually: put the files in place

~/.claude/skills/exploring-endpoint-execution-logs/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/exploring-endpoint-execution-logs/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about exploring-endpoint-execution-logs

How do you install exploring-endpoint-execution-logs in Claude Code?

Run npx skills add PostHog/skills --skill exploring-endpoint-execution-logs -a claude-code in your terminal. The tool registers the skill into your local Claude Code environment.

What does exploring-endpoint-execution-logs do?

It inspects individual PostHog endpoint runs by parsing log_entries records. It filters entries by log level, error type, execution path, and duration.

What is the difference between this skill and diagnosing-endpoint-performance?

This skill focuses on execution errors and individual run tokens for a single endpoint. Strategy decisions like materialization or cache TTL optimization belong to diagnosing-endpoint-performance.

Source text

SKILL.md · MIT
---
name: exploring-endpoint-execution-logs
description: >
  Explore and diagnose a PostHog endpoint's execution logs — error messages, failed runs, cache
  misses, slow runs, or unexpected row counts during endpoint invocations. Use when the user says
  "my endpoint is failing", "show me the logs for endpoint X", "what error did endpoint Y produce",
  "why did endpoint Z return no rows", "is this endpoint hitting cache", or "check the last N runs".
  Focused on a single named endpoint's runtime log entries, not project-wide auditing or query
  performance profiling.
---

# Exploring endpoint execution logs

Every endpoint run emits one execution log entry to PostHog's `log_entries` store. This skill
reads those entries for a specific endpoint to answer "what happened when it ran?". It is the
log-level counterpart to `diagnosing-endpoint-performance` (which reasons about cache/materialisation
strategy from config and `query_log`).

## When to use this skill

- "Why is my endpoint failing / erroring?"
- "Show me the logs / recent runs for endpoint X"
- "Did the last run hit cache? How many rows did it return?"
- "What happened the last time endpoint Y ran?"

If the question is "this endpoint is slow, what should I change?", use
`diagnosing-endpoint-performance`. If it's project-wide ("what can I clean up?"), use
`auditing-endpoints`.

## What an execution log entry looks like

Each run produces exactly one entry. The level is `INFO` on success and `ERROR` on failure, and the
message carries the extra data as searchable `key=value` tokens:

```text
Endpoint executed · path=materialized cache=hit duration_ms=142 rows=1024 version=3
Endpoint execution failed · path=inline error=ResolutionError version=3
```

Token meanings:

| Token         | Values                                                       | Meaning                                                        |
| ------------- | ------------------------------------------------------------ | -------------------------------------------------------------- |
| `path`        | `materialized` / `inline` / `ducklake` / `ducklake_fallback` | Which execution path ran                                       |
| `cache`       | `hit` / `miss`                                               | Whether the query result cache was used (omitted for ducklake) |
| `duration_ms` | integer                                                      | Wall-clock execution time                                      |
| `rows`        | integer                                                      | Number of result rows returned                                 |
| `version`     | integer                                                      | Which endpoint version ran                                     |
| `error`       | e.g. `ResolutionError`, `HogVMException`                     | Error class / HogQL code name (failures only)                  |

Each run gets a distinct `instance_id`, so logs group one-per-execution in the viewer.

## Available tools

| Tool            | Purpose                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `endpoint-logs` | Primary. Execution log entries for one endpoint by name. Filter by level, search, time range, instance_id; `limit` up to 500. |
| `endpoint-get`  | Endpoint config for context (current version, materialisation, query kind)                                                    |
| `execute-sql`   | Fallback / aggregation directly against `log_entries` (`log_source='endpoints'`)                                              |

## Filtering

`endpoint-logs` exposes the standard log filters:

- **level** — comma-separated, e.g. `ERROR` to see only failed runs, or `INFO,ERROR` for all.
- **search** — case-insensitive substring over the message. Because the extra data is in
  `key=value` tokens, you can search `cache=miss`, `path=inline`, `error=ResolutionError`, or a
  specific `version=3`.
- **after / before** — ISO timestamps to bound the time range.
- **instance_id** — pin a single execution.
- **limit** — 1–500 (default 50).

## Workflow

1. Identify the endpoint by name. If given a URL, parse it from
   `/api/projects/{team_id}/endpoints/{name}/run`.
2. Start broad: `endpoint-logs` for the endpoint with a recent time range. Skim levels and tokens.
3. Narrow to the symptom:
   - Failures → `level=ERROR`; read the `error=` token and `path=` to see where it broke.
   - Cache concerns → `search=cache=miss` to see how often runs miss cache.
   - Wrong results → compare `rows=` across runs, and `version=` to spot a regression after a
     version bump.
4. For counts/trends across many runs (e.g. error rate over a week), drop to `execute-sql` against
   `log_entries`:

   ```sql
   SELECT toDate(timestamp) AS day, upper(level) AS level, count() AS runs
   FROM log_entries
   WHERE log_source = 'endpoints' AND log_source_id = '<endpoint_uuid>'
   GROUP BY day, level ORDER BY day DESC
   ```

   Get the endpoint UUID from `endpoint-get` (the `log_source_id` is the endpoint id, not its name).

5. Summarize: what's failing, since when, on which version/path, and whether it's a config issue
   (hand off to `diagnosing-endpoint-performance`) or a query bug.

## Example interaction

```text
User: "weekly_signups started erroring this morning"

Agent steps:
- endpoint-logs weekly_signups, level=ERROR, after=<this morning>
  → several "Endpoint execution failed · path=inline error=ResolutionError version=5"
- endpoint-get weekly_signups → current version is v5 (bumped today)
- endpoint-logs weekly_signups, level=INFO, before=<this morning>
  → prior runs: "path=inline cache=hit ... version=4" succeeded

- "v5 (created this morning) is failing with a ResolutionError on the inline path — it can't
   resolve a table or field reference. v4 ran fine. This looks like a bad query in the new
   version. Want me to pull the v5 query (endpoint-versions) so we can fix it, or roll back to v4?"
```

## Important notes

- **One entry per run.** Don't expect step-by-step traces — endpoints log a single completion line.
  The detail lives in the tokens, not in multiple lines.
- **`log_source_id` is the endpoint UUID**, not the name. For `execute-sql`, fetch it via
  `endpoint-get` first.
- **Logs are retained ~90 days** (the `log_entries` TTL). Older runs won't appear.
- **Execution logs ≠ query performance.** `endpoint-logs` tells you what happened and why a run
  failed; for "should I materialise / bump cache TTL?" use `diagnosing-endpoint-performance`, which
  reasons over config and `query_log` cost metrics.
- **Best-effort emission.** A log line is emitted after each run but never blocks it — if a run
  succeeded for the caller but no log shows, the emit was dropped, not the query.

© PostHog · MIT · PostHog/skills

Similar skills

All skills for Backend and APIs →

From the same set112

The whole set →
signals-scout-csp-violations signals-scout-csp-violations monitors PostHog $csp_violation events for blocked domain clusters, per-directive bursts, and regression patterns. CX Codex +1 320installs signals-scout-error-tracking The signals-scout-error-tracking skill monitors PostHog $exception activity for bursts, stuck loops, fingerprint clusters, and status regressions. Use it for recurring error-signal checks. CX Codex +1 319installs signals-scout-experiments signals-scout-experiments monitors running PostHog A/B tests for sample ratio mismatch, flag mutations, broken exposure events, and lifecycle drift. Catches instrumentation flaws before teams act on biased results. CX Codex +1 319installs signals-scout-surveys signals-scout-surveys monitors PostHog surveys for score regressions, volume drops, and clusters open-text feedback into clear themes. CX Codex +1 319installs signals-scout-feature-flags signals-scout-feature-flags — a Claude Code skill that audits PostHog feature flags against incoming $feature_flag_called telemetry. It catches ghost flags, abrupt evaluation drops, and uncleaned code checks. CX Codex +1 318installs signals-scout-anomaly-detection signals-scout-anomaly-detection — a skill for Claude Code detects anomalies across saved PostHog insights, including sudden spikes, metric drops, and broken trends. Tracks key dashboards against seasonality-matched baselines. CX Codex +1 318installs signals-scout-web-analytics signals-scout-web-analytics — a scout skill for PostHog web analytics. Catches channel-level session drift, attribution breakage, and landing-page degradation by comparing each segment against its own baseline. CX Codex +1 317installs signals-scout-ai-observability signals-scout-ai-observability monitors PostHog LLM traces to uncover sudden cost spikes, latency drift, and error rate regressions. CX Codex +1 317installs

Project sponsors

Companies that keep this analytics open