> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt # API scopes Canonical URL: https://posthog.com/docs/api/scopes A scope grants access to one part of PostHog, such as feature flags or insights. You choose scopes when you create a [personal API key](https://posthog.com/docs/api/personal-api-keys.md) or a [project secret API key](https://posthog.com/docs/api/project-secret-api-keys.md), and when you authorize an [OAuth app](https://posthog.com/docs/api/oauth.md). Each scope has two levels: - **Read** (`:read`) lets the key or app view the data. - **Write** (`:write`) lets it view, create, change, and delete the data. **Request read or write, not both** Write access includes read access, so `feature_flag:write` already covers everything `feature_flag:read` does. For each part of PostHog, request `:read` if the key or app only views data, or `:write` if it also changes it. Grant only the scopes a key or app needs. A request that needs a scope the key or app doesn't have fails with a `403` error that names the missing scope. ## Scopes Product area Access ### Product analytics Scope What it covers Request one Alert Alerts on insights, metrics, and data warehouse sources, including thresholds, destinations, and snoozes. [Docs](https://posthog.com/docs/alerts.md) `alert:read`Read `alert:write`Read and write Annotation Annotations on charts, plus the change feed of feature flag, experiment, release, and annotation edits. [Docs](https://posthog.com/docs/data/annotations.md) `annotation:read`Read `annotation:write`Read and write Canvas Canvases, the agent-built apps filed into channels, including their source, versions, publishing, and state. `canvas:read`Read `canvas:write`Read and write Cross-project dashboard Dashboards the organization owns that show insights from one or more projects, and their tiles. - Applies to the whole organization, so keys limited to some projects can't have it. `cross_project_dashboard:read`Read `cross_project_dashboard:write`Read and write Dashboard Dashboards, including their tiles, text cards, widgets, and layout, and running the insights on them. [Docs](https://posthog.com/docs/product-analytics/dashboards.md) `dashboard:read`Read `dashboard:write`Read and write Dashboard template Dashboard templates, including their JSON schema and copying templates between projects. [Docs](https://posthog.com/docs/product-analytics/dashboards.md) `dashboard_template:read`Read `dashboard_template:write`Read and write Export Exported files of insights, dashboards, and session recordings, such as PNG, PDF, CSV, and video. `export:read`Read `export:write`Read and write Insight Insights, including their queries, results, and explanations, plus anomaly rates for trends insights. [Docs](https://posthog.com/docs/product-analytics/insights.md) `insight:read`Read `insight:write`Read and write Insight variable SQL variables that insights and dashboards can reference and override. [Docs](https://posthog.com/docs/data-warehouse/sql/variables.md) `insight_variable:read`Read `insight_variable:write`Read and write Notebook Notebooks and the reusable widgets you can embed in them. [Docs](https://posthog.com/docs/notebooks.md) `notebook:read`Read `notebook:write`Read and write Query Running SQL and insight queries on your project's data, plus event, session, and web vitals lookups. [Docs](https://posthog.com/docs/api/queries.md) `query:read`Read Sharing configuration Public sharing and embed settings for dashboards, insights, recordings, and notebooks, including passwords. [Docs](https://posthog.com/docs/product-analytics/sharing.md) - sharing\_configuration:read: Reads the access tokens of public sharing links, which keep working after this token expires. - sharing\_configuration:write: Creates public sharing links that anyone with the link can open. `sharing_configuration:read`Read `sharing_configuration:write`Read and write Subscription Scheduled email and Slack subscriptions to insights and dashboards, including their delivery history. [Docs](https://posthog.com/docs/product-analytics/subscriptions.md) `subscription:read`Read `subscription:write`Read and write ### Web, marketing & revenue analytics Scope What it covers Request one Heatmap Click and scroll heatmap data, page screenshots, and saved heatmaps. [Docs](https://posthog.com/docs/toolbar/heatmaps.md) `heatmap:read`Read `heatmap:write`Read and write Marketing analytics Marketing analytics conversion goals, marketing data sources, UTM audits, and conversion recordings. [Docs](https://posthog.com/docs/web-analytics/marketing-analytics.md) `marketing_analytics:read`Read `marketing_analytics:write`Read and write Web analytics Web analytics digests, bot rules, path cleaning suggestions, achievements, and AI search prompts. [Docs](https://posthog.com/docs/web-analytics.md) `web_analytics:read`Read `web_analytics:write`Read and write ### Events, people & data model Scope What it covers Request one Action Actions, the named combinations of events and page elements, including where they are referenced. [Docs](https://posthog.com/docs/data/actions.md) `action:read`Read `action:write`Read and write Cohort Cohorts, including their filters, static member lists, calculation history, and where they are used. [Docs](https://posthog.com/docs/data/cohorts.md) `cohort:read`Read `cohort:write`Read and write Element Autocaptured page elements, with the click stats and values used by heatmaps and the toolbar. [Docs](https://posthog.com/docs/product-analytics/autocapture.md) `element:read`Read `element:write`Read and write Event definition Event definitions, schemas, and property groups, including tags, verification, and generated type definitions. [Docs](https://posthog.com/docs/data/events.md) `event_definition:read`Read `event_definition:write`Read and write Event filter The project's ingestion filter that drops matching events, plus its dry-run and drop metrics. [Docs](https://posthog.com/docs/data/event-filtering.md) `event_filter:read`Read `event_filter:write`Read and write Group Group types and groups used in group analytics, including their properties. [Docs](https://posthog.com/docs/product-analytics/group-analytics.md) `group:read`Read `group:write`Read and write Person Persons and their properties, including updating, splitting, and deleting persons and their data. [Docs](https://posthog.com/docs/data/persons.md) `person:read`Read `person:write`Read and write Property definition Event and person property definitions, including their descriptions, types, tags, and verification status. [Docs](https://posthog.com/docs/data.md) `property_definition:read`Read `property_definition:write`Read and write ### Session replay Scope What it covers Request one Replay scanner Replay Vision scanners, including their observations, backfills, clusters, scouts, and usage quota. [Docs](https://posthog.com/docs/replay-vision.md) `replay_scanner:read`Read `replay_scanner:write`Read and write Session recording Session recordings, including their snapshots, console logs, viewed status, and deletion. [Docs](https://posthog.com/docs/session-replay.md) `session_recording:read`Read `session_recording:write`Read and write Session recording playlist Session replay collections and saved filters, including the recordings added to them. [Docs](https://posthog.com/docs/session-replay.md) `session_recording_playlist:read`Read `session_recording_playlist:write`Read and write Vision alert Replay Vision alerts, including their conditions, destinations, and the events that triggered them. [Docs](https://posthog.com/docs/replay-vision/alerts.md) `vision_alert:read`Read `vision_alert:write`Read and write ### Feature flags, experiments & surveys Scope What it covers Request one Early access feature Early access features users can opt into, including their stage and linked feature flag. [Docs](https://posthog.com/docs/feature-flags/early-access-feature-management.md) - Early access features manage a linked feature flag, so this key needs write access to feature flags too. `early_access_feature:read`Read `early_access_feature:write`Read and write Experiment Experiments and no-code web experiments, including launching, pausing, shipping variants, and results. [Docs](https://posthog.com/docs/experiments.md) `experiment:read`Read `experiment:write`Read and write Holdout Experiment holdouts, the groups of users kept out of experiments to measure their combined impact. [Docs](https://posthog.com/docs/experiments/holdouts.md) `experiment_holdout:read`Read `experiment_holdout:write`Read and write Shared metric Shared experiment metrics that can be reused across experiments. [Docs](https://posthog.com/docs/experiments/metrics.md) `experiment_saved_metric:read`Read `experiment_saved_metric:write`Read and write Feature flag Feature flags, including their release conditions, variants, payloads, and rollout history. [Docs](https://posthog.com/docs/feature-flags.md) `feature_flag:read`Read `feature_flag:write`Read and write Product tour Product tours, including their steps, targeting, drafts, and publishing. `product_tour:read`Read `product_tour:write`Read and write Survey Surveys, including their questions, targeting, responses, stats, and launch status. [Docs](https://posthog.com/docs/surveys.md) - Surveys with targeting also manage a feature flag, so this key needs write access to feature flags too. `survey:read`Read `survey:write`Read and write ### Error tracking, logs & tracing Scope What it covers Request one Error tracking Error tracking issues, releases, symbol sets, alerts, and grouping, assignment, and suppression rules. [Docs](https://posthog.com/docs/error-tracking.md) `error_tracking:read`Read `error_tracking:write`Read and write Logs Logs, including queries, saved views, alerts, and sampling, retention, and log-to-metric rules. [Docs](https://posthog.com/docs/logs.md) `logs:read`Read `logs:write`Read and write Metrics Metrics, including PromQL queries, metric labels, and suggested or imported metrics dashboards. [Docs](https://posthog.com/docs/metrics.md) `metrics:read`Read `metrics:write`Read and write Tracing Distributed tracing spans and traces, saved views, retention, and service health and service map data. [Docs](https://posthog.com/docs/distributed-tracing/start-here.md) `tracing:read`Read `tracing:write`Read and write ### Developer experience Scope What it covers Request one Engineering analytics Engineering analytics for connected GitHub repos: pull requests, CI runs, deploys, DORA metrics, and settings. `engineering_analytics:read`Read `engineering_analytics:write`Read and write Stamphog Stamphog pull request approvals, including repository settings, review runs, reviewer routing, and digests. `stamphog:read`Read `stamphog:write`Read and write Visual review Visual review repos, CI runs, screenshot snapshots, baselines, approvals, and quarantined snapshots. `visual_review:read`Read `visual_review:write`Read and write ### LLM & MCP analytics Scope What it covers Request one Cluster Clusters of similar AI traces, including clustering runs, jobs, and their event filter settings. [Docs](https://posthog.com/docs/ai-observability/clusters.md) `ai_observability_clusters:read`Read `ai_observability_clusters:write`Read and write Dataset Datasets for AI evals, including their items, revisions, archiving, and exports. [Docs](https://posthog.com/docs/ai-evals/datasets.md) `dataset:read`Read `dataset:write`Read and write Evaluation LLM evaluations, including their runs, scores, reports, backfills over past data, and offline evals. [Docs](https://posthog.com/docs/ai-evals.md) `evaluation:read`Read `evaluation:write`Read and write AI observability AI observability traces, trace reviews, review queues, scores, summaries, and evaluation settings. [Docs](https://posthog.com/docs/ai-observability.md) `llm_analytics:read`Read `llm_analytics:write`Read and write LLM gateway Sending LLM requests through the PostHog LLM gateway, where PostHog has enabled it. - llm\_gateway:read is granted only by PostHog, so OAuth apps can't request it. `llm_gateway:read`Read LLM playground Listing models and running prompts in the LLM playground. [Docs](https://posthog.com/docs/ai-observability/playground.md) `llm_playground:read`Read `llm_playground:write`Read and write LLM prompt LLM prompts in prompt management, including versions, labels, and fetching prompts by name. [Docs](https://posthog.com/docs/prompt-management.md) `llm_prompt:read`Read `llm_prompt:write`Read and write LLM provider key LLM provider API keys used for evaluations and the playground, including validating them. - llm\_provider\_key:write: Stores and changes LLM provider API keys. `llm_provider_key:read`Read `llm_provider_key:write`Read and write LLM skill Skills for AI agents with their files and versions, the skills marketplace, and PostHog Review skill settings. [Docs](https://posthog.com/docs/skills.md) `llm_skill:read`Read `llm_skill:write`Read and write MCP analytics MCP analytics sessions, tool calls, intent clusters, and feedback submitted for your MCP server. [Docs](https://posthog.com/docs/mcp-analytics.md) `mcp_analytics:read`Read `mcp_analytics:write`Read and write Offline evaluation ingestion Creating offline evaluation experiments, uploading their results, and marking them completed or failed. [Docs](https://posthog.com/docs/ai-evals/offline-evals.md) `offline_evaluation_ingestion:write`Read and write Tagger Taggers that automatically label your AI generations, including testing tagger code on sample events. [Docs](https://posthog.com/docs/ai-evals/taggers.md) `tagger:read`Read `tagger:write`Read and write ### Data warehouse & pipelines Scope What it covers Request one Batch export Batch exports to destinations like S3, BigQuery, and Snowflake, including runs, backfills, and file downloads. [Docs](https://posthog.com/docs/data-pipelines/batch-exports.md) `batch_export:read`Read `batch_export:write`Read and write Endpoint Endpoints, saved queries served as API routes, including runs, versions, materialization, and OpenAPI specs. [Docs](https://posthog.com/docs/endpoints.md) `endpoint:read`Read `endpoint:write`Read and write External data source Data warehouse sources, their synced tables and sync settings, and the destinations they write to. [Docs](https://posthog.com/docs/data-pipelines/sources.md) `external_data_source:read`Read `external_data_source:write`Read and write Workflow Workflows and messaging, including email templates, message categories, opt-outs, and suppression lists. [Docs](https://posthog.com/docs/workflows.md) - hog\_flow:write: Runs workflow code that can use the stored credentials of the project's integrations. `hog_flow:read`Read `hog_flow:write`Read and write Hog function Data pipeline destinations, transformations, and other Hog functions, plus their templates. [Docs](https://posthog.com/docs/data-pipelines.md) - hog\_function:write: Runs code, including on your website, that can use the stored credentials of the project's integrations. `hog_function:read`Read `hog_function:write`Read and write Plugin Legacy apps (plugins), their configurations, and their logs. [Docs](https://posthog.com/docs/data-pipelines.md) `plugin:read`Read `plugin:write`Read and write Streamlit app Streamlit apps that run on your PostHog data, including their source, versions, and running state. `streamlit_app:read`Read `streamlit_app:write`Read and write Warehouse table Data warehouse tables, including their schemas, file uploads, column descriptions, and column statistics. [Docs](https://posthog.com/docs/data-warehouse.md) `warehouse_table:read`Read `warehouse_table:write`Read and write Warehouse view Data warehouse views and joins, including materialization runs, lineage, folders, and saved expressions. [Docs](https://posthog.com/docs/data-warehouse/views.md) `warehouse_view:read`Read `warehouse_view:write`Read and write Webhook REST hook subscriptions used by the Zapier integration to send matching events to a target URL. [Docs](https://posthog.com/docs/libraries/zapier.md) `webhook:read`Read `webhook:write`Read and write ### Messaging Scope What it covers Request one Transactional email Making a template transactional and sending email from it, and reading a sent email's status with a project secret key. [Docs](https://posthog.com/docs/workflows/transactional-emails.md) `transactional_email:read`Read `transactional_email:write`Read and write ### AI & context management tools Scope What it covers Request one Approvals Approval policies and change requests that gate changes, including approving, rejecting, or canceling them. [Docs](https://posthog.com/docs/settings/approvals.md) - approvals:write: Approves or rejects change requests that gate other changes. `approvals:read`Read `approvals:write`Read and write Autoresearch Autoresearch prediction pipelines, their training runs, models, daily scoring runs, and steering suggestions. - autoresearch:write: Starts agent runs that get their own longer-lived token. `autoresearch:read`Read `autoresearch:write`Read and write Business knowledge Business knowledge sources, documents, and settings that give PostHog AI context, plus gap suggestions. [Docs](https://posthog.com/docs/business-knowledge.md) `business_knowledge:read`Read `business_knowledge:write`Read and write AI conversation PostHog AI chat conversations, including starting them, sending messages, and canceling or queueing replies. [Docs](https://posthog.com/docs/posthog-ai.md) `conversation:read`Read `conversation:write`Read and write Data catalog Data catalog metrics, certifications on warehouse tables and views, and proposed relationships between tables. [Docs](https://posthog.com/docs/semantic-layer.md) `data_catalog:read`Read `data_catalog:write`Read and write Data catalog approval Approving Data catalog metrics, certifying tables, and accepting relationships, so agents cannot self-approve. [Docs](https://posthog.com/docs/semantic-layer/governance.md) `data_catalog_approval:write`Read and write Field note Field notes left on your site with the toolbar, including creating, updating, and resolving them. [Docs](https://posthog.com/docs/toolbar.md) `field_note:read`Read `field_note:write`Read and write Inbox Inbox reports with their checks and artifacts, signal source settings, and signal processing controls. [Docs](https://posthog.com/docs/self-driving/inbox.md) `inbox:read`Read `inbox:write`Read and write PostHog Review PostHog Review code reviews of your pull requests, plus repository settings and per-user review choices. `review_hog:read`Read `review_hog:write`Read and write Signals agent Self-driving scouts, including their configuration, runs, findings, notes, memories, and suggested scouts. [Docs](https://posthog.com/docs/self-driving/scouts.md) `signal_scout:read`Read `signal_scout:write`Read and write Self-driving usage Self-driving usage over the last 30 days, broken down by scout and by signal source. [Docs](https://posthog.com/docs/self-driving/pricing.md) `signal_usage:read`Read Task Agent tasks and their runs, logs, artifacts, threads, channels, and sandbox environments. [Docs](https://posthog.com/docs/tasks.md) `task:read`Read `task:write`Read and write Today home The Today home page, including highlights, the key numbers you pin, and report excerpts. `today:read`Read `today:write`Read and write ### Customers & support Scope What it covers Request one Account Customer analytics accounts, their custom properties, relationships, notes, notebooks, and event streams. [Docs](https://posthog.com/docs/customer-analytics/start-here.md) `account:read`Read `account:write`Read and write Customer analytics Customer analytics feature requests, product areas, account tracking rules, and Slack announcements. [Docs](https://posthog.com/docs/customer-analytics/start-here.md) `customer_analytics:read`Read `customer_analytics:write`Read and write Customer journey Customer journeys in Customer analytics, each built on a saved insight. [Docs](https://posthog.com/docs/customer-analytics/customer-journeys.md) `customer_journey:read`Read `customer_journey:write`Read and write Customer profile config Layouts of the person and group profile pages in Customer analytics, including their content and sidebar. [Docs](https://posthog.com/docs/customer-analytics/customer-profiles.md) `customer_profile_config:read`Read `customer_profile_config:write`Read and write Customer task Customer tasks on accounts in Customer analytics, with status, assignee, due date, and activity history. [Docs](https://posthog.com/docs/customer-analytics/start-here.md) `customer_task:read`Read `customer_task:write`Read and write Support ticket Support tickets fetched through the external ticket API, used only by project secret API keys. [Docs](https://posthog.com/docs/support.md) `support_ticket:read`Read `support_ticket:write`Read and write Ticket Support tickets, including their messages, notes, status, assignment, saved views, and macros. [Docs](https://posthog.com/docs/support.md) `ticket:read`Read `ticket:write`Read and write Usage metric Customer analytics usage metrics that track how each account or group uses your product. [Docs](https://posthog.com/docs/customer-analytics/usage-metrics.md) `usage_metric:read`Read `usage_metric:write`Read and write ### Setup & data management Scope What it covers Request one Data deletion Requests to delete events, event properties, or persons from a project, with previews of the affected data. `data_deletion:read`Read `data_deletion:write`Read and write Health issue Problems found by project health checks, such as outdated SDKs or failing syncs, and snoozing them. [Docs](https://posthog.com/docs/health-checks.md) `health_issue:read`Read `health_issue:write`Read and write Ingestion warning Ingestion warnings for events and person or group updates that were ingested with problems. [Docs](https://posthog.com/docs/data/ingestion-warnings.md) `ingestion_warning:read`Read Integration Project integrations with third-party services such as Slack, plus connections to other PostHog projects. `integration:read`Read Organization integration Organization-wide integrations, such as Vercel or AWS Marketplace, including disconnecting them. [Docs](https://posthog.com/docs/integrations/vercel-marketplace.md) - organization\_integration:write: Connects and changes organization-wide integrations and their stored credentials. - Applies to the whole organization, so keys limited to some projects can't have it. `organization_integration:read`Read `organization_integration:write`Read and write Product enablement Turning on products such as Session replay, Error tracking, and Conversations for a project. `product_enablement:write`Read and write ### Organization & account Scope What it covers Request one Access control Who can access each resource, including project-wide defaults, per-resource rules, and property-level rules. [Docs](https://posthog.com/docs/settings/access-control.md) - access\_control:write: Changes who can access resources in this project. `access_control:read`Read `access_control:write`Read and write Activity log The project's activity log of changes to resources, with filters and exports. [Docs](https://posthog.com/docs/settings/activity-logs.md) `activity_log:read`Read `activity_log:write`Read and write Billing The organization's subscription, usage, spend, forecasts, invoices, and limits, across all its projects. [Docs](https://posthog.com/docs/billing/common-questions.md) - billing:read: Reads the whole organization's billing details, not just this project's. - billing:write: Changes the organization's subscription and payment details. `billing:read`Read `billing:write`Read and write Comment Comments and discussion threads on PostHog resources, including resolving them and mirroring them to Slack. [Docs](https://posthog.com/docs/data/comments.md) `comment:read`Read `comment:write`Read and write File system The project file tree: folders, saved items, search, and recently viewed files. `file_system:read`Read File system shortcut Shortcuts pinned to items in the project file tree. `file_system_shortcut:read`Read `file_system_shortcut:write`Read and write Legal document Your organization's BAA and DPA documents, including requesting, downloading, and deleting them. [Docs](https://posthog.com/docs/privacy.md) `legal_document:read`Read `legal_document:write`Read and write Organization Organization settings, verified domains, roles, SSO providers, and proxies, across the whole organization. [Docs](https://posthog.com/docs/settings/organizations.md) - organization:write: Changes organization settings, including roles and OAuth apps. - Applies to the whole organization, so keys limited to some projects can't have it. `organization:read`Read `organization:write`Read and write Organization member Organization members and invites, including membership levels and removing members. [Docs](https://posthog.com/docs/settings/organizations.md) - organization\_member:write: Invites and removes organization members and changes their roles, so it can give people access beyond this token's scopes. - Applies to the whole organization, so keys limited to some projects can't have it. `organization_member:read`Read `organization_member:write`Read and write Project Projects and their settings, including how data is ingested, plus creating and modifying projects. [Docs](https://posthog.com/docs/settings/projects.md) `project:read`Read `project:write`Read and write Uploaded media Images uploaded to your project, such as those in dashboard text cards, including uploads and deletion. `uploaded_media:read`Read `uploaded_media:write`Read and write User Your own user account, including profile, settings, two-factor setup, login sessions, and integrations. [Docs](https://posthog.com/docs/settings/account-settings.md) - user:read: Reads the account details of the user the token acts as, including every organization and project they belong to. `user:read`Read Workload trust policy Trust policies that let workloads such as CI jobs exchange an OIDC token for a PostHog project token. `workload_trust_policy:read`Read Workload trust policy request Requests asking an organization admin for a workload trust policy, and approving or rejecting them. `workload_trust_policy_request:read`Read `workload_trust_policy_request:write`Read and write ## FAQ **Why can't my OAuth app request some scopes?** PostHog grants some scopes only through its own admin tools, so an OAuth app that registers itself can't request them. The notes under each description mark these scopes. The scopes an OAuth app can request are also listed in `scopes_supported` in the [authorization server metadata](https://posthog.com/docs/api/oauth.md#oauth-server-endpoints). **Can I get this list as JSON?** Yes. `https://oauth.posthog.com/oauth/scopes` returns every scope on this page, with the same descriptions. It doesn't need authentication.