API scopes

Contents

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 or a project secret API key, and when you authorize an OAuth app.

Each scope has two levels:

  • Read (<object>:read) lets the key or app view the data.
  • Write (<object>: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 analytics

Scope
What it covers
Request one
Alert
Alerts on insights, metrics, and data warehouse sources, including thresholds, destinations, and snoozes. Docs
alert:readRead
alert:writeRead and write
Annotation
Annotations on charts, plus the change feed of feature flag, experiment, release, and annotation edits. Docs
annotation:readRead
annotation:writeRead and write
Canvas
Canvases, the agent-built apps filed into channels, including their source, versions, publishing, and state.
canvas:readRead
canvas:writeRead 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:readRead
cross_project_dashboard:writeRead and write
Dashboard
Dashboards, including their tiles, text cards, widgets, and layout, and running the insights on them. Docs
dashboard:readRead
dashboard:writeRead and write
Dashboard template
Dashboard templates, including their JSON schema and copying templates between projects. Docs
dashboard_template:readRead
dashboard_template:writeRead and write
Export
Exported files of insights, dashboards, and session recordings, such as PNG, PDF, CSV, and video.
export:readRead
export:writeRead and write
Insight
Insights, including their queries, results, and explanations, plus anomaly rates for trends insights. Docs
insight:readRead
insight:writeRead and write
Insight variable
SQL variables that insights and dashboards can reference and override. Docs
insight_variable:readRead
insight_variable:writeRead and write
Notebook
Notebooks and the reusable widgets you can embed in them. Docs
notebook:readRead
notebook:writeRead and write
Query
Running SQL and insight queries on your project's data, plus event, session, and web vitals lookups. Docs
query:readRead
Sharing configuration
Public sharing and embed settings for dashboards, insights, recordings, and notebooks, including passwords. Docs
  • 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:readRead
sharing_configuration:writeRead and write
Subscription
Scheduled email and Slack subscriptions to insights and dashboards, including their delivery history. Docs
subscription:readRead
subscription:writeRead and write

Web, marketing & revenue analytics

Scope
What it covers
Request one
Heatmap
Click and scroll heatmap data, page screenshots, and saved heatmaps. Docs
heatmap:readRead
heatmap:writeRead and write
Marketing analytics
Marketing analytics conversion goals, marketing data sources, UTM audits, and conversion recordings. Docs
marketing_analytics:readRead
marketing_analytics:writeRead and write
Web analytics
Web analytics digests, bot rules, path cleaning suggestions, achievements, and AI search prompts. Docs
web_analytics:readRead
web_analytics:writeRead 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
action:readRead
action:writeRead and write
Cohort
Cohorts, including their filters, static member lists, calculation history, and where they are used. Docs
cohort:readRead
cohort:writeRead and write
Element
Autocaptured page elements, with the click stats and values used by heatmaps and the toolbar. Docs
element:readRead
element:writeRead and write
Event definition
Event definitions, schemas, and property groups, including tags, verification, and generated type definitions. Docs
event_definition:readRead
event_definition:writeRead and write
Event filter
The project's ingestion filter that drops matching events, plus its dry-run and drop metrics. Docs
event_filter:readRead
event_filter:writeRead and write
Group
Group types and groups used in group analytics, including their properties. Docs
group:readRead
group:writeRead and write
Person
Persons and their properties, including updating, splitting, and deleting persons and their data. Docs
person:readRead
person:writeRead and write
Property definition
Event and person property definitions, including their descriptions, types, tags, and verification status. Docs
property_definition:readRead
property_definition:writeRead 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
replay_scanner:readRead
replay_scanner:writeRead and write
Session recording
Session recordings, including their snapshots, console logs, viewed status, and deletion. Docs
session_recording:readRead
session_recording:writeRead and write
Session recording playlist
Session replay collections and saved filters, including the recordings added to them. Docs
session_recording_playlist:readRead
session_recording_playlist:writeRead and write
Vision alert
Replay Vision alerts, including their conditions, destinations, and the events that triggered them. Docs
vision_alert:readRead
vision_alert:writeRead 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
  • Early access features manage a linked feature flag, so this key needs write access to feature flags too.
early_access_feature:readRead
early_access_feature:writeRead and write
Experiment
Experiments and no-code web experiments, including launching, pausing, shipping variants, and results. Docs
experiment:readRead
experiment:writeRead and write
Holdout
Experiment holdouts, the groups of users kept out of experiments to measure their combined impact. Docs
experiment_holdout:readRead
experiment_holdout:writeRead and write
Shared metric
Shared experiment metrics that can be reused across experiments. Docs
experiment_saved_metric:readRead
experiment_saved_metric:writeRead and write
Feature flag
Feature flags, including their release conditions, variants, payloads, and rollout history. Docs
feature_flag:readRead
feature_flag:writeRead and write
Product tour
Product tours, including their steps, targeting, drafts, and publishing.
product_tour:readRead
product_tour:writeRead and write
Survey
Surveys, including their questions, targeting, responses, stats, and launch status. Docs
  • Surveys with targeting also manage a feature flag, so this key needs write access to feature flags too.
survey:readRead
survey:writeRead 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
error_tracking:readRead
error_tracking:writeRead and write
Logs
Logs, including queries, saved views, alerts, and sampling, retention, and log-to-metric rules. Docs
logs:readRead
logs:writeRead and write
Metrics
Metrics, including PromQL queries, metric labels, and suggested or imported metrics dashboards. Docs
metrics:readRead
metrics:writeRead and write
Tracing
Distributed tracing spans and traces, saved views, retention, and service health and service map data. Docs
tracing:readRead
tracing:writeRead 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:readRead
engineering_analytics:writeRead and write
Stamphog
Stamphog pull request approvals, including repository settings, review runs, reviewer routing, and digests.
stamphog:readRead
stamphog:writeRead and write
Visual review
Visual review repos, CI runs, screenshot snapshots, baselines, approvals, and quarantined snapshots.
visual_review:readRead
visual_review:writeRead 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
ai_observability_clusters:readRead
ai_observability_clusters:writeRead and write
Dataset
Datasets for AI evals, including their items, revisions, archiving, and exports. Docs
dataset:readRead
dataset:writeRead and write
Evaluation
LLM evaluations, including their runs, scores, reports, backfills over past data, and offline evals. Docs
evaluation:readRead
evaluation:writeRead and write
AI observability
AI observability traces, trace reviews, review queues, scores, summaries, and evaluation settings. Docs
llm_analytics:readRead
llm_analytics:writeRead 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:readRead
LLM playground
Listing models and running prompts in the LLM playground. Docs
llm_playground:readRead
llm_playground:writeRead and write
LLM prompt
LLM prompts in prompt management, including versions, labels, and fetching prompts by name. Docs
llm_prompt:readRead
llm_prompt:writeRead 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:readRead
llm_provider_key:writeRead and write
LLM skill
Skills for AI agents with their files and versions, the skills marketplace, and PostHog Review skill settings. Docs
llm_skill:readRead
llm_skill:writeRead and write
MCP analytics
MCP analytics sessions, tool calls, intent clusters, and feedback submitted for your MCP server. Docs
mcp_analytics:readRead
mcp_analytics:writeRead and write
Offline evaluation ingestion
Creating offline evaluation experiments, uploading their results, and marking them completed or failed. Docs
offline_evaluation_ingestion:writeRead and write
Tagger
Taggers that automatically label your AI generations, including testing tagger code on sample events. Docs
tagger:readRead
tagger:writeRead 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
batch_export:readRead
batch_export:writeRead and write
Endpoint
Endpoints, saved queries served as API routes, including runs, versions, materialization, and OpenAPI specs. Docs
endpoint:readRead
endpoint:writeRead and write
External data source
Data warehouse sources, their synced tables and sync settings, and the destinations they write to. Docs
external_data_source:readRead
external_data_source:writeRead and write
Workflow
Workflows and messaging, including email templates, message categories, opt-outs, and suppression lists. Docs
  • hog_flow:write: Runs workflow code that can use the stored credentials of the project's integrations.
hog_flow:readRead
hog_flow:writeRead and write
Hog function
Data pipeline destinations, transformations, and other Hog functions, plus their templates. Docs
  • hog_function:write: Runs code, including on your website, that can use the stored credentials of the project's integrations.
hog_function:readRead
hog_function:writeRead and write
Plugin
Legacy apps (plugins), their configurations, and their logs. Docs
plugin:readRead
plugin:writeRead and write
Streamlit app
Streamlit apps that run on your PostHog data, including their source, versions, and running state.
streamlit_app:readRead
streamlit_app:writeRead and write
Warehouse table
Data warehouse tables, including their schemas, file uploads, column descriptions, and column statistics. Docs
warehouse_table:readRead
warehouse_table:writeRead and write
Warehouse view
Data warehouse views and joins, including materialization runs, lineage, folders, and saved expressions. Docs
warehouse_view:readRead
warehouse_view:writeRead and write
Webhook
REST hook subscriptions used by the Zapier integration to send matching events to a target URL. Docs
webhook:readRead
webhook:writeRead 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
transactional_email:readRead
transactional_email:writeRead 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
  • approvals:write: Approves or rejects change requests that gate other changes.
approvals:readRead
approvals:writeRead 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:readRead
autoresearch:writeRead and write
Business knowledge
Business knowledge sources, documents, and settings that give PostHog AI context, plus gap suggestions. Docs
business_knowledge:readRead
business_knowledge:writeRead and write
AI conversation
PostHog AI chat conversations, including starting them, sending messages, and canceling or queueing replies. Docs
conversation:readRead
conversation:writeRead and write
Data catalog
Data catalog metrics, certifications on warehouse tables and views, and proposed relationships between tables. Docs
data_catalog:readRead
data_catalog:writeRead and write
Data catalog approval
Approving Data catalog metrics, certifying tables, and accepting relationships, so agents cannot self-approve. Docs
data_catalog_approval:writeRead and write
Field note
Field notes left on your site with the toolbar, including creating, updating, and resolving them. Docs
field_note:readRead
field_note:writeRead and write
Inbox
Inbox reports with their checks and artifacts, signal source settings, and signal processing controls. Docs
inbox:readRead
inbox:writeRead and write
PostHog Review
PostHog Review code reviews of your pull requests, plus repository settings and per-user review choices.
review_hog:readRead
review_hog:writeRead and write
Signals agent
Self-driving scouts, including their configuration, runs, findings, notes, memories, and suggested scouts. Docs
signal_scout:readRead
signal_scout:writeRead and write
Self-driving usage
Self-driving usage over the last 30 days, broken down by scout and by signal source. Docs
signal_usage:readRead
Task
Agent tasks and their runs, logs, artifacts, threads, channels, and sandbox environments. Docs
task:readRead
task:writeRead and write
Today home
The Today home page, including highlights, the key numbers you pin, and report excerpts.
today:readRead
today:writeRead and write

Customers & support

Scope
What it covers
Request one
Account
Customer analytics accounts, their custom properties, relationships, notes, notebooks, and event streams. Docs
account:readRead
account:writeRead and write
Customer analytics
Customer analytics feature requests, product areas, account tracking rules, and Slack announcements. Docs
customer_analytics:readRead
customer_analytics:writeRead and write
Customer journey
Customer journeys in Customer analytics, each built on a saved insight. Docs
customer_journey:readRead
customer_journey:writeRead and write
Customer profile config
Layouts of the person and group profile pages in Customer analytics, including their content and sidebar. Docs
customer_profile_config:readRead
customer_profile_config:writeRead and write
Customer task
Customer tasks on accounts in Customer analytics, with status, assignee, due date, and activity history. Docs
customer_task:readRead
customer_task:writeRead and write
Support ticket
Support tickets fetched through the external ticket API, used only by project secret API keys. Docs
support_ticket:readRead
support_ticket:writeRead and write
Ticket
Support tickets, including their messages, notes, status, assignment, saved views, and macros. Docs
ticket:readRead
ticket:writeRead and write
Usage metric
Customer analytics usage metrics that track how each account or group uses your product. Docs
usage_metric:readRead
usage_metric:writeRead 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:readRead
data_deletion:writeRead and write
Health issue
Problems found by project health checks, such as outdated SDKs or failing syncs, and snoozing them. Docs
health_issue:readRead
health_issue:writeRead and write
Ingestion warning
Ingestion warnings for events and person or group updates that were ingested with problems. Docs
ingestion_warning:readRead
Integration
Project integrations with third-party services such as Slack, plus connections to other PostHog projects.
integration:readRead
Organization integration
Organization-wide integrations, such as Vercel or AWS Marketplace, including disconnecting them. Docs
  • 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:readRead
organization_integration:writeRead and write
Product enablement
Turning on products such as Session replay, Error tracking, and Conversations for a project.
product_enablement:writeRead 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
  • access_control:write: Changes who can access resources in this project.
access_control:readRead
access_control:writeRead and write
Activity log
The project's activity log of changes to resources, with filters and exports. Docs
activity_log:readRead
activity_log:writeRead and write
Billing
The organization's subscription, usage, spend, forecasts, invoices, and limits, across all its projects. Docs
  • 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:readRead
billing:writeRead and write
Comment
Comments and discussion threads on PostHog resources, including resolving them and mirroring them to Slack. Docs
comment:readRead
comment:writeRead and write
File system
The project file tree: folders, saved items, search, and recently viewed files.
file_system:readRead
File system shortcut
Shortcuts pinned to items in the project file tree.
file_system_shortcut:readRead
file_system_shortcut:writeRead and write
Your organization's BAA and DPA documents, including requesting, downloading, and deleting them. Docs
legal_document:readRead
legal_document:writeRead and write
Organization
Organization settings, verified domains, roles, SSO providers, and proxies, across the whole organization. Docs
  • 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:readRead
organization:writeRead and write
Organization member
Organization members and invites, including membership levels and removing members. Docs
  • 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:readRead
organization_member:writeRead and write
Project
Projects and their settings, including how data is ingested, plus creating and modifying projects. Docs
project:readRead
project:writeRead and write
Uploaded media
Images uploaded to your project, such as those in dashboard text cards, including uploads and deletion.
uploaded_media:readRead
uploaded_media:writeRead and write
User
Your own user account, including profile, settings, two-factor setup, login sessions, and integrations. Docs
  • user:read: Reads the account details of the user the token acts as, including every organization and project they belong to.
user:readRead
Workload trust policy
Trust policies that let workloads such as CI jobs exchange an OIDC token for a PostHog project token.
workload_trust_policy:readRead
Workload trust policy request
Requests asking an organization admin for a workload trust policy, and approving or rejecting them.
workload_trust_policy_request:readRead
workload_trust_policy_request:writeRead 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.

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.

Still have questions?

Was this page useful?