Skip to main content

​
POST /decide

The /decide endpoint is the primary way SDKs and clients evaluate feature flags. It returns which flags are enabled for a given user or group, along with their values and optional payloads.
This endpoint is designed for SDK use. For server-side evaluation, consider using the Local Evaluation endpoint at /api/feature_flag/local_evaluation instead.

​
Request Body

​
api_key
string
required
Your project API key (public token)
​
distinct_id
string
required
Unique identifier for the user/person
​
person_properties
object
Person properties to use for flag evaluation
​
groups
object
Group identifiers for group-based flags. Keys are group type names, values are group keys.
{
  "company": "acme-inc",
  "organization": "org-123"
}
​
group_properties
object
Properties for each group type
{
  "company": {
    "plan": "enterprise",
    "seats": 50
  }
}
​
$anon_distinct_id
string
Anonymous ID before user identification (for experience continuity)
​
geoip_disable
boolean
default:"false"
Disable GeoIP lookup for this request

​
Response

​
featureFlags
object
Object mapping flag keys to their evaluated values. Boolean flags return true/false, multivariate flags return the variant key.
{
  "new-dashboard": true,
  "checkout-variant": "test",
  "beta-feature": false
}
​
featureFlagPayloads
object
Object mapping flag keys to their JSON payloads (if configured)
{
  "checkout-variant": {"button_color": "green"}
}
​
errorsWhileComputingFlags
boolean
Whether any errors occurred during flag evaluation

​
Examples

​
Basic Flag Evaluation

curl -X POST https://app.posthog.com/decide \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "phc_your_project_api_key",
    "distinct_id": "user_123"
  }'

​
With Person Properties

curl -X POST https://app.posthog.com/decide \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "phc_your_project_api_key",
    "distinct_id": "user_123",
    "person_properties": {
      "email": "[email protected]",
      "plan": "premium",
      "signup_date": "2024-01-15"
    }
  }'

​
With Group Properties

curl -X POST https://app.posthog.com/decide \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "phc_your_project_api_key",
    "distinct_id": "user_123",
    "groups": {
      "company": "acme-inc"
    },
    "group_properties": {
      "company": {
        "plan": "enterprise",
        "seats": 50,
        "industry": "technology"
      }
    }
  }'

​
With Anonymous ID for Experience Continuity

curl -X POST https://app.posthog.com/decide \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "phc_your_project_api_key",
    "distinct_id": "user_123",
    "$anon_distinct_id": "anon_456"
  }'

​
Response Examples

​
Boolean Flags

{
  "featureFlags": {
    "new-dashboard": true,
    "beta-feature": false,
    "dark-mode": true
  },
  "errorsWhileComputingFlags": false
}

​
Multivariate Flags with Payloads

{
  "featureFlags": {
    "checkout-flow": "test",
    "button-color": "green",
    "pricing-page": "variant-b"
  },
  "featureFlagPayloads": {
    "checkout-flow": {
      "steps": 3,
      "show_trust_badges": true
    },
    "button-color": {
      "hex": "#00FF00"
    },
    "pricing-page": {
      "layout": "comparison",
      "highlight_plan": "pro"
    }
  },
  "errorsWhileComputingFlags": false
}

​
With Errors

{
  "featureFlags": {
    "new-dashboard": true
  },
  "errorsWhileComputingFlags": true
}
Best Practices:
  • The /decide endpoint performs person and group lookups, which can be slower than local evaluation
  • For high-traffic server-side applications, use the Local Evaluation endpoint instead
  • Cache flag results on the client side when possible
  • SDKs automatically handle caching and polling for you
  • Include relevant properties to ensure accurate flag evaluation
  • Use anonymous IDs for experience continuity when users aren’t yet identified

​
SDKs

Most PostHog SDKs use the /decide endpoint under the hood. Here’s how to use feature flags in various SDKs: 
// PostHog automatically calls /decide
if (posthog.isFeatureEnabled('new-dashboard')) {
  // Show new dashboard
}

// Get variant value
const variant = posthog.getFeatureFlag('checkout-flow');

// Get payload
const payload = posthog.getFeatureFlagPayload('checkout-flow');

Build docs developers (and LLMs) love

Get started for freeTalk to us