feature_flags

Test feature flag evaluation against a specific user at an optional point in time.

This endpoint allows testing how a feature flag would evaluate for a specific user, optionally at a historical timestamp. When a timestamp is provided, both the flag conditions and person properties are evaluated as they existed at that time.

post/api/projects/{project_id}/feature_flags/{id}/test_evaluation/

Request

  • Base URL: https://us.posthog.com
  • URL: https://us.posthog.com/api/projects/{project_id}/feature_flags/{id}/test_evaluation/
  • Auth: HTTP bearer

Path parameters

idinteger required

A unique integer value identifying this feature flag.

project_idstring required

Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Request body

distinct_idstring

User distinct ID to test against (mutually exclusive with person_id)

person_idstring

Person ID to test against (mutually exclusive with distinct_id)

timestampstring date-time nullable

Optional point-in-time to evaluate the flag against — both flag conditions and person properties are reconstructed as they existed at that timestamp. ISO 8601 with timezone, e.g. 2026-04-29T15:30:00Z or 2026-04-29T15:30:00+00:00. Naive timestamps (no timezone) are interpreted as UTC.

groupsunknown

Response

flag_keystring required

Feature flag key

resultunknown required
reasonstring required

The reason for the evaluation result

reason_descriptionstring nullable

Human-readable explanation of the evaluation result. Set when the reason code is coarse, for example a non-match decided by a behavioral or realtime cohort whose membership is not fully evaluated here, which can disagree with the cohort's member list.

condition_indexinteger nullable required

The index of the condition that matched, if applicable

payloadunknown required
person_propertiesobject required

Person properties at the time of evaluation (for historical evaluations)

evaluation_distinct_idstring nullable required

The distinct_id used for rollout/variant bucketing. Echoes the caller-provided distinct_id when one was sent; null on the person_id path so the endpoint doesn't leak the person's other distinct_ids to a feature_flag:read-only token.

Changes

No recorded changes to this operation across all 1 revision of this API.