# PostHog tools (https://www.shipfox.io/docs/integrations/posthog/tools)

Description: Look up PostHog's read-only tools, selectors, inputs, and examples for agent steps and tool steps.

This reference lists the shipped PostHog tool catalog. See the [PostHog
overview](https://www.shipfox.io/docs/integrations/posthog) for authentication and project boundaries.

## Tool catalog [#tool-catalog]

All tools require the read access configured in the [personal API key
recipe](https://www.shipfox.io/docs/integrations/posthog/setup#create-the-personal-api-key).

### Tools

#### `execute-sql`

Execute a read-only HogQL query against PostHog data.

**Access:** read.

**Sensitive:** Yes.

**Required permissions:** `read`

**Selector tokens:** `execute-sql`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `connectionId` | string | Optional | Optional id of a data warehouse connection (e.g. Postgres, MySQL, Snowflake, Redshift). When set, the query runs live against that source instead of the ClickHouse catalog, and may only reference that source's tables. Discover connection ids with external-data-sources-connections-list, then list a connection's tables by running `SELECT table_name FROM system.information_schema.tables` with that connectionId set. |
| `query` | string | Required | The final SQL query to be executed. Minimum length 1. |
| `sendRawQuery` | boolean | Optional | Send `query` to the connection verbatim instead of compiling it from HogQL first. Use this for SQL only that connection's own engine understands, such as vendor-specific functions. Requires connectionId, and works only on a pure direct connection (access_method 'direct'), not on a synced source with live queries enabled. The connection is read-only and accepts a single statement. |
| `truncate` | boolean | Optional | Whether to truncate large blob/JSON values in results. Defaults to true. Set to false when you need full untruncated results (e.g., for dumping to a file). Default true. |

#### `read-data-schema`

Read the available PostHog event, entity, and property schema.

**Access:** read.

**Sensitive:** No.

**Required permissions:** `read`

**Selector tokens:** `read-data-schema`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `query` | object (one of 7 shapes) | Required | The data schema query to execute. |
| `query.kind` | constant `"events"` \| constant `"event_properties"` \| constant `"entity_properties"` \| constant `"action_properties"` \| constant `"entity_property_values"` \| constant `"event_property_values"` \| constant `"action_property_values"` | Conditional |  |
| `query.limit` | integer | Conditional | Number of events to return per page. Minimum 1. Maximum 500. Default 500. |
| `query.offset` | integer | Conditional | Number of events to skip for pagination. Minimum 0. Maximum 9,007,199,254,740,991. Default 0. |
| `query.event_name` | string | Conditional | The name of the event that you want to retrieve properties for. |
| `query.entity` | string | Conditional | The entity to read: `person`, `session` for the columns of the `sessions` table, or a group type name. The plural form of any of these is accepted too. |
| `query.action_id` | integer | Conditional | The ID of the action that you want to retrieve properties for. Minimum -9,007,199,254,740,991. Maximum 9,007,199,254,740,991. |
| `query.property_name` | string | Conditional | Verified property name of an entity. |

#### `insights-list`

List saved insights in the current PostHog project.

**Access:** read.

**Sensitive:** No.

**Required permissions:** `read`

**Selector tokens:** `insights-list`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `created_by` | string | Optional | JSON-encoded array of user IDs. Only returns insights whose `created_by` is in the list, e.g. `[1,42]`. |
| `created_date_from` | string | Optional | Filter by `created_at > created_date_from`. Accepts absolute or relative dates. |
| `created_date_to` | string | Optional | Filter by `created_at < created_date_to`. Accepts absolute or relative dates. |
| `dashboards` | string | Optional | JSON-encoded array of dashboard IDs. Returns insights attached to every listed dashboard (AND). |
| `date_from` | string | Optional | Filter by `last_modified_at > date_from`. Accepts absolute dates (`2025-04-23`) or relative strings (`-7d`, `-1m`). |
| `date_to` | string | Optional | Filter by `last_modified_at < date_to`. Accepts absolute dates or relative strings. |
| `favorited` | boolean | Optional | Include this parameter (any value) to restrict results to insights marked as favorited. |
| `include_dashboards` | boolean | Optional | Opt in to receiving the deprecated `dashboards` field in insight payloads. Once opt-in enforcement is enabled, API-token callers stop receiving it by default; use `dashboard_tiles` instead. |
| `insight` | string: `FUNNELS`, `JOURNEYS`, `JSON`, `LIFECYCLE`, `PATHS`, `RETENTION`, `SQL`, `STICKINESS`, `TRENDS` | Optional | Restrict to a single insight type. `JSON` matches non-wrapper query insights; `SQL` matches HogQL queries. |
| `last_viewed_date_from` | string | Optional | Filter by `last_viewed_at > last_viewed_date_from`. Accepts absolute or relative dates. |
| `last_viewed_date_to` | string | Optional | Filter by `last_viewed_at < last_viewed_date_to`. Accepts absolute or relative dates. |
| `limit` | number | Optional | Number of results to return per page. |
| `offset` | number | Optional | The initial index from which to return the results. |
| `saved` | boolean | Optional | When truthy, restricts results to insights that are saved (or attached to a visible dashboard). When falsy, only unsaved insights. |
| `search` | string | Optional | Search term matched across name, derived_name, description, and tag names. Returns exact (case-insensitive substring) matches only; if no exact match exists, returns similar (fuzzy trigram) matches instead. Each result's `search_match_type` is `exact` or `similar`. |
| `short_id` | string | Optional |  |
| `tags` | string | Optional | JSON-encoded array of tag names. Returns insights with any of the listed tags. |
| `user` | boolean | Optional | Include this parameter (any value) to restrict results to insights created by the authenticated user. |

#### `insight-get`

Retrieve a saved insight definition by numeric id or short id.

**Access:** read.

**Sensitive:** No.

**Required permissions:** `read`

**Selector tokens:** `insight-get`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `filters_override` | string \| object | Optional | Object (or pre-encoded JSON string) to override the insight's filters for this request only (not persisted). Top-level keys replace; nested values are not deep-merged: pass the complete value for any key you override. Accepts the same keys as the dashboard filters schema (e.g., `date_from`, `date_to`, `properties`). Ignored when accessed via a sharing token. |
| `id` | number \| string | Required | Numeric primary key or 8-character `short_id` (for example `AaVQ8Ijw`) identifying the insight. |
| `include_dashboards` | boolean | Optional | Opt in to receiving the deprecated `dashboards` field in insight payloads. Once opt-in enforcement is enabled, API-token callers stop receiving it by default; use `dashboard_tiles` instead. |
| `variables_override` | string \| object | Optional | Object (or pre-encoded JSON string) to override the insight's HogQL variables for this request only (not persisted). Format: {"<variable_id>": {"code_name": "<code_name>", "variableId": "<variable_id>", "value": <new_value>}}. Each entry must include `code_name`: partial entries are silently dropped. The simplest workflow is to call `insight-get` first, copy the matching entry from the response, and mutate `value`. Top-level keys replace; nested values are not deep-merged. Ignored when accessed via a sharing token. |

#### `insight-query`

Run a saved insight and return its query results.

**Access:** read.

**Sensitive:** Yes.

**Required permissions:** `read`

**Selector tokens:** `insight-query`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `filters_override` | string \| object | Optional | Object (or pre-encoded JSON string) to override the insight's filters for this run only (not persisted). Top-level keys replace; nested values are not deep-merged: pass the complete value for any key you override. Accepts the same keys as the dashboard filters schema (e.g., `date_from`, `date_to`, `properties`). Ignored when accessed via a sharing token. |
| `insightId` | string \| number | Required | The insight to run: its numeric `id` or 8-character `short_id`. |
| `output_format` | string: `optimized`, `json` | Optional | Output format. "optimized" returns a human-readable summary from server-side formatters (recommended for analysis). "json" returns the raw query results as JSON. Default "optimized". |
| `variables_override` | string \| object | Optional | Object (or pre-encoded JSON string) to override the insight's HogQL variables for this run only (not persisted). Format: {"<variable_id>": {"code_name": "<code_name>", "variableId": "<variable_id>", "value": <new_value>}}. Each entry must include `code_name`: partial entries are silently dropped. The simplest workflow is to call `insight-get` first, copy the matching entry from the response's query variables, and mutate `value`. Top-level keys replace; nested values are not deep-merged. Ignored when accessed via a sharing token. |

#### `dashboards-get-all`

List dashboards in the current PostHog project.

**Access:** read.

**Sensitive:** No.

**Required permissions:** `read`

**Selector tokens:** `dashboards-get-all`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `exclude_generated` | boolean | Optional | Optional. Exclude dashboards that PostHog generated. |
| `folder` | string | Optional | Optional. Return only dashboards filed directly in this project-tree folder, e.g. 'Unfiled/Dashboards'. An empty string matches dashboards at the project root. Nested sub-folders are not included. |
| `limit` | number | Optional | Number of results to return per page. |
| `offset` | number | Optional | The initial index from which to return the results. |
| `pinned` | boolean | Optional | Optional. Return only pinned dashboards. |
| `search` | string | Optional | Optional. Match against dashboard `name`, `description`, and tag names. Returns exact (case-insensitive substring) matches only; if no exact match exists, returns similar (fuzzy trigram: typos, transpositions, prefix-as-you-type) matches instead. Results are then ordered by relevance, then pinned status, then name; each result's `search_match_type` is `exact` or `similar`. When omitted, dashboards are ordered by pinned status then alphabetical name. Capped at 200 characters; longer queries return a 400 error. |

#### `dashboard-get`

Retrieve a dashboard and its tiles by id.

**Access:** read.

**Sensitive:** No.

**Required permissions:** `read`

**Selector tokens:** `dashboard-get`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `filters_override` | string \| object | Optional | Object (or pre-encoded JSON string) to override dashboard filters for this request only (not persisted). Top-level keys replace; nested values are not deep-merged: pass the complete value for any key you override. Accepts the same keys as the dashboard filters schema (e.g., `date_from`, `date_to`, `properties`). Ignored when accessed via a sharing token. |
| `id` | number | Required | A unique integer value identifying this dashboard. |
| `include_dashboards` | boolean | Optional | Opt in to receiving the deprecated `dashboards` field in insight payloads. Once opt-in enforcement is enabled, API-token callers stop receiving it by default; use `dashboard_tiles` instead. |
| `variables_override` | string \| object | Optional | Object (or pre-encoded JSON string) to override dashboard variables for this request only (not persisted). Format: {"<variable_id>": {"code_name": "<code_name>", "variableId": "<variable_id>", "value": <new_value>}}. Each entry must include `code_name`: partial entries are silently dropped. The simplest workflow is to call `dashboard-get` first, copy the matching entry from the response, and mutate `value`. Top-level keys replace; nested values are not deep-merged. Ignored when accessed via a sharing token. |

#### `dashboard-insights-run`

Run all insights on a dashboard and return their results.

**Access:** read.

**Sensitive:** Yes.

**Required permissions:** `read`

**Selector tokens:** `dashboard-insights-run`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `filters_override` | string \| object | Optional | Object (or pre-encoded JSON string) to override dashboard filters for this request only (not persisted). Top-level keys replace; nested values are not deep-merged: pass the complete value for any key you override. Accepts the same keys as the dashboard filters schema (e.g., `date_from`, `date_to`, `properties`). Ignored when accessed via a sharing token. |
| `id` | number | Required | A unique integer value identifying this dashboard. |
| `output_format` | string: `json`, `optimized` | Optional | 'optimized' (default) returns LLM-friendly formatted text per insight. 'json' returns the raw query result objects. |
| `refresh` | string: `blocking`, `force_blocking`, `force_cache` | Optional | Cache behavior. 'force_cache' (default) serves from cache even if stale. 'blocking' uses cache if fresh, otherwise recalculates. 'force_blocking' always recalculates. |
| `variables_override` | string \| object | Optional | Object (or pre-encoded JSON string) to override dashboard variables for this request only (not persisted). Format: {"<variable_id>": {"code_name": "<code_name>", "variableId": "<variable_id>", "value": <new_value>}}. Each entry must include `code_name`: partial entries are silently dropped. The simplest workflow is to call `dashboard-get` first, copy the matching entry from the response, and mutate `value`. Top-level keys replace; nested values are not deep-merged. Ignored when accessed via a sharing token. |

#### `query-error-tracking-issues-list`

List and aggregate error tracking issues.

**Access:** read.

**Sensitive:** Yes.

**Required permissions:** `read`

**Selector tokens:** `query-error-tracking-issues-list`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `assignee` | object \| null | Optional | Filter by issue assignee. Omit to include all assignees. |
| `assignee.id` | string \| number | Required | User ID or role UUID to filter by. |
| `assignee.type` | string: `user`, `role` | Required | Assignee target type: user or role.  * `user` - user * `role` - role |
| `dateRange` | object | Optional | Date range for issue aggregates. Defaults to the last 7 days. |
| `dateRange.date_from` | string | Optional | Start of the date range as an ISO timestamp or relative date such as -7d. Defaults to -7d. |
| `dateRange.date_to` | string \| null | Optional | End of the date range as an ISO timestamp or relative date. Defaults to now when omitted. |
| `filePath` | string | Optional | Search stack-frame source/file path text. Maximum length 1,000. |
| `filterGroup` | array of object | Optional | Advanced flat AND property filters. Prefer typed shortcut fields when they fit. HogQL filters are rejected. |
| `filterGroup[].key` | string | Required | Key of the property you're filtering on. For example `email` or `$current_url` |
| `filterGroup[].operator` | string \| string \| null | Optional | Default "exact". |
| `filterGroup[].type` | string \| string | Optional | Default "event". |
| `filterGroup[].value` | string \| number \| boolean \| array of string \| number | Required | Value of your filter. For example `test@example.com` or `https://example.com/test/`. Can be an array for an OR query, like `["test@example.com","ok@example.com"]` |
| `filterTestAccounts` | boolean | Optional | When true, exclude internal/test account data from results. Defaults to true. Default true. |
| `fingerprint` | string \| array of string | Optional | Filter by exact exception fingerprint hash, not fuzzy search. |
| `library` | string \| array of string | Optional | Filter by SDK/library value from event $lib, for example posthog-js. |
| `limit` | number | Optional | Page size. Minimum 1. Maximum 100. Default 25. |
| `offset` | number | Optional | Pagination offset. Minimum 0. Default 0. |
| `orderBy` | string: `last_seen`, `first_seen`, `occurrences`, `users`, `sessions` | Optional | Field used to sort issues. Defaults to occurrences.  * `last_seen` - last_seen * `first_seen` - first_seen * `occurrences` - occurrences * `users` - users * `sessions` - sessions Default "occurrences". |
| `orderDirection` | string: `ASC`, `DESC` | Optional | Sort direction. Defaults to DESC.  * `ASC` - ASC * `DESC` - DESC Default "DESC". |
| `personId` | string | Optional | Filter by exact PostHog person UUID. |
| `release` | string | Optional | Filter by exact release ID, version, or git commit ID captured in $exception_releases. Maximum length 500. |
| `searchQuery` | string | Optional | Free-text search across exception types, values, stack frames, and email fields. Maximum length 500. |
| `status` | string: `archived`, `active`, `resolved`, `pending_release`, `suppressed`, `all` | Optional | Filter by issue status. Defaults to active.  * `archived` - archived * `active` - active * `resolved` - resolved * `pending_release` - pending_release * `suppressed` - suppressed * `all` - all Default "active". |
| `url` | string | Optional | Filter by current URL substring. Maximum length 1,000. |
| `user` | string | Optional | Search user/email text. Maximum length 500. |
| `volumeResolution` | number | Optional | Number of volume buckets. Defaults to 0 for compact aggregate counts. Minimum 0. Maximum 200. Default 0. |

#### `query-error-tracking-issue`

Retrieve details and impact for an error tracking issue.

**Access:** read.

**Sensitive:** Yes.

**Required permissions:** `read`

**Selector tokens:** `query-error-tracking-issue`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `dateRange` | object | Optional | Date range for issue impact and latest-event metadata. Defaults to the last 7 days. |
| `dateRange.date_from` | string | Optional | Start of the date range as an ISO timestamp or relative date such as -7d. Defaults to -7d. |
| `dateRange.date_to` | string \| null | Optional | End of the date range as an ISO timestamp or relative date. Defaults to now when omitted. |
| `filterTestAccounts` | boolean | Optional | When true, exclude internal/test account data from results. Defaults to true. Default true. |
| `includeSparkline` | boolean | Optional | Set true to include a compact numeric occurrence sparkline. Defaults to false. Default false. |
| `issueId` | string | Required | Error tracking issue ID. |
| `volumeResolution` | number | Optional | Volume buckets. Maximum 200. Minimum 0. Maximum 200. Default 0. |

#### `feature-flag-get-all`

List feature flags in the current PostHog project.

**Access:** read.

**Sensitive:** No.

**Required permissions:** `read`

**Selector tokens:** `feature-flag-get-all`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `active` | string: `STALE`, `false`, `true` | Optional |  |
| `archived` | string: `false`, `true` | Optional | Filter by archived state. When omitted, archived flags are excluded. |
| `created_by_id` | string | Optional | Filter by the user(s) who created the feature flag. Accepts a single user ID, or a JSON-encoded / comma-separated list of user IDs to match any of them. |
| `eligible_for_experiment` | string: `true` | Optional | When 'true', only return flags that can back an experiment: multivariate with 2-20 variants. Any other value is ignored. |
| `evaluation_runtime` | string: `all`, `client`, `server` | Optional | Filter feature flags by their evaluation runtime. |
| `excluded_properties` | string | Optional | JSON-encoded list of feature flag keys to exclude from the results. |
| `excluded_tags` | string | Optional | JSON-encoded list of tag names to exclude. Flags carrying any of these tags are filtered out. |
| `has_evaluation_contexts` | string: `false`, `true` | Optional | Filter feature flags by presence of evaluation contexts. 'true' returns only flags with at least one evaluation context, 'false' returns only flags without. |
| `key` | string | Optional | Filter by exact feature flag key match. Case insensitive. |
| `limit` | number | Optional | Number of results to return per page. |
| `offset` | number | Optional | The initial index from which to return the results. |
| `search` | string | Optional | Search by feature flag key or name (case-insensitive). Use this to find the flag ID for get/update/delete tools. |
| `tags` | string | Optional | JSON-encoded list of tag names to filter feature flags by. |
| `type` | string: `boolean`, `experiment`, `multivariant`, `remote_config` | Optional |  |

#### `feature-flag-get-definition`

Retrieve a feature flag definition by id.

**Access:** read.

**Sensitive:** No.

**Required permissions:** `read`

**Selector tokens:** `feature-flag-get-definition`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | number | Required | A unique integer value identifying this feature flag. |

#### `experiment-list`

List experiments in the current PostHog project.

**Access:** read.

**Sensitive:** No.

**Required permissions:** `read`

**Selector tokens:** `experiment-list`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `archived` | boolean | Optional | Filter by archived state. Defaults to non-archived experiments only. |
| `created_by_id` | string | Optional | Filter to experiments created by the given user(s). Accepts a single user ID, or a JSON-encoded / comma-separated list of user IDs to match any of them. |
| `event` | string | Optional | Filter to experiments whose metrics reference this event name. Matches events used directly in metric queries as well as events behind any actions those metrics reference. |
| `excluded_tags` | string | Optional | JSON-encoded list of tag names. Excludes experiments carrying any of the given tags, even when they also carry non-excluded tags. |
| `feature_flag_id` | number | Optional | Filter to experiments linked to the given feature flag ID. |
| `limit` | number | Optional | Number of results to return per page. |
| `offset` | number | Optional | The initial index from which to return the results. |
| `order` | string | Optional | Field to order by. Prefix with '-' for descending. Allowlisted fields include name, created_at, updated_at, start_date, end_date, duration, and status. |
| `prompt_name` | string | Optional | Filter to experiments created from an LLM prompt with this name. Matches experiments whose parameters.prompt_metadata.name equals the given value. |
| `search` | string | Optional | Free-text search applied to the experiment name (case-insensitive). |
| `status` | string: `all`, `complete`, `draft`, `exposure_frozen`, `paused`, `running`, `stopped` | Optional | Filter by experiment status. Values: "draft" (not yet launched), "running" (launched, flag active), "paused" (launched, flag deactivated: mutually exclusive with running), "exposure_frozen" (launched, enrollment frozen to the already-exposed cohort while metrics keep flowing), "stopped" or "complete" (both mean ended), "all" (no filter). Defaults to all non-archived experiments. |
| `tags` | string | Optional | JSON-encoded list of tag names. Returns experiments carrying at least one of the given tags, e.g. `["growth", "checkout"]`. |

#### `experiment-get`

Retrieve an experiment by id.

**Access:** read.

**Sensitive:** No.

**Required permissions:** `read`

**Selector tokens:** `experiment-get`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | number | Required | A unique integer value identifying this experiment. |

#### `experiment-results-get`

Retrieve comprehensive results for an experiment.

**Access:** read.

**Sensitive:** Yes.

**Required permissions:** `read`

**Selector tokens:** `experiment-results-get`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | number | Required | The ID of the experiment to get comprehensive results for |
| `refresh` | boolean | Optional | Force refresh of results instead of using cached values. Defaults to false. Default false. |

#### `surveys-get-all`

List surveys in the current PostHog project.

**Access:** read.

**Sensitive:** No.

**Required permissions:** `read`

**Selector tokens:** `surveys-get-all`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `archived` | boolean | Optional |  |
| `created_by` | number | Optional | Filter surveys by the ID of the user who created them. |
| `ids` | array of string | Optional | Multiple values may be separated by commas. |
| `limit` | number | Optional | Number of results to return per page. |
| `offset` | number | Optional | The initial index from which to return the results. |
| `search` | string | Optional | Match against survey `name` and `description`. Returns exact (case-insensitive substring) matches only; if no exact match exists, returns similar (fuzzy trigram: typos, prefix-as-you-type) matches instead. Each result's `search_match_type` is `exact` or `similar`. |
| `status` | string: `complete`, `draft`, `running` | Optional | Filter surveys by their current status.  * `draft` - Draft * `running` - Running * `complete` - Complete |
| `type` | string: `api`, `external_survey`, `popover`, `widget` | Optional | * `popover` - popover * `widget` - widget * `external_survey` - external survey * `api` - api |

#### `survey-get`

Retrieve a survey by id.

**Access:** read.

**Sensitive:** No.

**Required permissions:** `read`

**Selector tokens:** `survey-get`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | Required | A UUID string identifying this survey. |

#### `survey-stats`

Retrieve response statistics for a survey.

**Access:** read.

**Sensitive:** Yes.

**Required permissions:** `read`

**Selector tokens:** `survey-stats`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `date_from` | string (date-time) | Optional | Optional ISO timestamp for start date (e.g. 2024-01-01T00:00:00Z) |
| `date_to` | string (date-time) | Optional | Optional ISO timestamp for end date (e.g. 2024-01-31T23:59:59Z) |
| `id` | string | Required | A UUID string identifying this survey. |
| `include_per_question_stats` | boolean | Optional | When true, also return per-question response counts and answer distributions. Adds one extra HogQL query per question, so leave off unless you need the breakdown. |

#### `docs-search`

Search the PostHog documentation.

**Access:** read.

**Sensitive:** No.

**Required permissions:** `read`

**Selector tokens:** `docs-search`

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `query` | string | Required | Natural-language description of what to find in the PostHog documentation. Inkeep performs hybrid (semantic + full-text) RAG, so phrase the query the way a user would ask the question. |