PostHog

Let hires query your product analytics in PostHog, read saved insights, check feature flags and, with your approval, turn them on or off.

Explore 7 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With PostHog (Cloud US, Cloud EU or your own server), a hire can:

run a HogQL query (PostHog's SQL) over your events, people and sessions,
list and read your saved insights, with their latest numbers,
list feature flags: on or off, how much of whom gets them, and their variants,
turn a feature flag on or off, once a person approves,
look at recent events and find people, without their personal details.

Personal data stays in PostHog

Hires never see people's names, full email addresses, IP addresses or exact locations. People show as their PostHog ID and a masked address like j***@acme.com; events show who did them only as a short fingerprint. Emails and IP addresses in query results are replaced with [email] and [ip].

1. Make a personal API key in PostHog

Straight there: PostHog Cloud US or EU; on your own PostHog, Settings → Personal API keys.

In PostHog, open Settings → Personal API keys and click Create personal API key. Name it Roster.
Organization & project access: only the project hires should use.
Scopes: Query read, Insight read, Feature flag read, Person read. Add Feature flag write only if hires may turn flags on or off.
Create it and copy the key (it starts with phx_).
Note the project's ID under Settings → Project (a number).

2. Connect it in Roster

Open Integrations → Tools → Add a tool, search for PostHog and choose it.
Where your PostHog is: Cloud US, Cloud EU, or self-hosted (then give the address you open PostHog at).
Personal API key and Project ID: paste them.
Click Connect.

Roster checks the key when you click Connect. If what you paste doesn't look like a key (personal API keys start with phx_), the form says so straight away. Once it's accepted, the connection shows Connected as the project's name and its organisation. If it's refused, Roster says what to fix (a mistyped key, a missing permission) and saves nothing.

3. Give hires access

On the hire's Tools tab, click Give access on PostHog:

Read only: queries, insights, flags, events and people.
Read and write: also turn feature flags on or off.
Flags it may turn on or off: flag keys, one per line. Any other flag is refused. Leave it empty for any flag.

Turning a flag on or off always asks first

A flag change reaches your users at once, so it waits for a person's approval: the hire asks in the thread, and when the approver says yes, Roster makes exactly that change, once.

What hires get back

Queries return at most 100 rows unless the hire asks for up to 500, and long answers are cut short with a note saying so. Hires are told to count and group in the query rather than pull raw rows. PostHog stops a query after 10 seconds; a hire whose query times out narrows it.

If something goes wrong

"API key missing required scope": edit the key in PostHog and add the scope named.
"Not found": check the project ID, and that the key is allowed to use that project.
Too many requests: PostHog allows about 240 analytics calls a minute per key; Roster waits and tries again.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect PostHog and give hires access. It updates with each release.

Authentication and requested permissions

The account or app you connect sets the outer limit. Each hire's access can narrow it further. Connecting a tool gives it to no hire until you give access on that hire's Tools tab.

API key or access token

In PostHog: Settings → Personal API keys → Create, with Query, Insight, Feature flag and Person read (and Feature flag write to turn flags on or off), for this project only.

When making a key, use these permissions from the connection guide:

Project: Read
Query: Read
Insight: Read
Person: Read
Feature flag: Read (Write to turn flags on or off)

Connection fields

PostHog connection fields
Field	What to provide
Personal API key `token` Required · sealed secret	In PostHog: Settings → Personal API keys → Create, with Query, Insight, Feature flag and Person read (and Feature flag write to turn flags on or off), for this project only.
Where your PostHog is `region` Optional	Use the value for your account or connection. Choices: PostHog Cloud US (us.posthog.com) (us); PostHog Cloud EU (eu.posthog.com) (eu); Self-hosted (self). Starts with: `us`.
PostHog address `url` Optional	The address you open PostHog at. Shown when `region: self`.
Project ID `projectId` Required	In PostHog: Settings → Project → Project ID (a number).

Per-hire limits

Read-only hires receive only actions that read. Read-and-write access also allows actions that change things, where the connection itself permits them. An empty resource allowlist usually means everything the connected account can reach; each field below explains its meaning.

PostHog per-hire limits
Field	What to provide
Flags it may turn on or off `flags` Optional	Feature flag keys, one per line. Leave empty for any flag (turning one on or off always asks a person first).

Actions

7 actions: 6 only read and 1 change something. A read action may still need approval when your workspace or hire is set to ask. A locked approval requirement always applies.

Find an actionAccess

7 of 7 actions. Open an action for its arguments and full input schema.

run_queryRead only

Run a HogQL (PostHog's SQL) SELECT over this project's data: events, persons, sessions, groups. Example: SELECT event, count() FROM events WHERE timestamp > now() - INTERVAL 7 DAY GROUP BY event ORDER BY count() DESC. Aggregate where you can: at most `limit` rows come back, and emails and IPs in results are hidden. Read only.

Approval: Uses your workspace and hire approval settings.

Arguments for run_query
Argument	Type	Details
`query`Required	string	one HogQL SELECT (or WITH … SELECT), no semicolons
`limit`Optional	integer	See input schema below.Default: `100`

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 8,
      "maxLength": 8000,
      "description": "one HogQL SELECT (or WITH … SELECT), no semicolons"
    },
    "limit": {
      "default": 100,
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  },
  "required": [
    "query"
  ]
}

list_insightsRead only

Saved insights (charts) in this PostHog project, recently changed first, by words in their name.

Approval: Uses your workspace and hire approval settings.

Arguments for list_insights
Argument	Type	Details
`search`Optional	string	See input schema below.
`limit`Optional	integer	See input schema below.Default: `20`

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "maxLength": 200
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  }
}

get_insightRead only

One saved insight with its latest result: trend totals and recent values, or funnel steps.

Approval: Uses your workspace and hire approval settings.

Arguments for get_insight
Argument	Type	Details
`insight`Required	string	its short id (from list_insights)

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "insight": {
      "type": "string",
      "pattern": "^[A-Za-z0-9]{1,20}$",
      "description": "its short id (from list_insights)"
    }
  },
  "required": [
    "insight"
  ]
}

list_feature_flagsRead only

Feature flags in this project: on or off, how much of whom gets them, and their variants.

Approval: Uses your workspace and hire approval settings.

Arguments for list_feature_flags
Argument	Type	Details
`search`Optional	string	See input schema below.
`active`Optional	"on" \| "off"	See input schema below.

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "maxLength": 200
    },
    "active": {
      "type": "string",
      "enum": [
        "on",
        "off"
      ]
    }
  }
}

set_feature_flagRead and write

Turn a feature flag on or off. Users see the change at once, so it waits for a person's approval: Roster asks in the thread and makes exactly that change, once, when they approve.

Approval: Always asks for approval.

Arguments for set_feature_flag
Argument	Type	Details
`key`Required	string	the flag's key
`on`Required	boolean	true to turn it on, false to turn it off

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 400,
      "description": "the flag's key"
    },
    "on": {
      "type": "boolean",
      "description": "true to turn it on, false to turn it off"
    }
  },
  "required": [
    "key",
    "on"
  ]
}

list_eventsRead only

Recent events, newest first, by event name and time: each with its time, a short fingerprint of who did it, and its non-personal properties. For counts and trends use run_query instead.

Approval: Uses your workspace and hire approval settings.

Arguments for list_events
Argument	Type	Details
`event`Optional	string	an event name such as $pageview or signed_up
`after`Optional	string	See input schema below.
`before`Optional	string	See input schema below.
`limit`Optional	integer	See input schema below.Default: `25`

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "event": {
      "description": "an event name such as $pageview or signed_up",
      "type": "string",
      "maxLength": 200
    },
    "after": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    },
    "before": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    },
    "limit": {
      "default": 25,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  }
}

find_peopleRead only

People in this project matching words (an email, a name or an id): their PostHog id, a masked email, and when they were first and last seen. Never their name, full email or other personal details.

Approval: Uses your workspace and hire approval settings.

Arguments for find_people
Argument	Type	Details
`search`Required	string	See input schema below.
`limit`Optional	integer	See input schema below.Default: `10`

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "limit": {
      "default": 10,
      "type": "integer",
      "minimum": 1,
      "maximum": 25
    }
  },
  "required": [
    "search"
  ]
}

Watches and incoming events

No built-in watch is declared. Give a hire a scheduled responsibility if it should check this service regularly.
No incoming webhook handler is declared for this integration.

Limits and troubleshooting

Permission errors: check both the connected account's rights and the hire's resource and read/write limits.
Expired or revoked access: reconnect or replace the key on the connection.
Rate limits and unavailable services can interrupt work. The hire's timecard records the outcome.
The action schema describes accepted inputs. It does not grant additional access or bypass approvals.

Service documentation · Integration source reference

1. Make a personal API key in PostHogCopy Anchor Link

2. Connect it in RosterCopy Anchor Link

3. Give hires accessCopy Anchor Link

What hires get backCopy Anchor Link

If something goes wrongCopy Anchor Link

Tools and permissions reference

Authentication and requested permissions

API key or access token

Connection fields

Per-hire limits

Actions

Watches and incoming events

Limits and troubleshooting

On this page

1. Make a personal API key in PostHog

2. Connect it in Roster

3. Give hires access

What hires get back

If something goes wrong