Evaluate Feature Flags

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

string

required

Your project API key (public token)

string

required

Unique identifier for the user/person

object

Person properties to use for flag evaluation

object

Group identifiers for group-based flags. Keys are group type names, values are group keys.

{
  "company": "acme-inc",
  "organization": "org-123"
}

object

Properties for each group type

{
  "company": {
    "plan": "enterprise",
    "seats": 50
  }
}

string

Anonymous ID before user identification (for experience continuity)

boolean

default:"false"

Disable GeoIP lookup for this request

Response

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
}

object

Object mapping flag keys to their JSON payloads (if configured)

{
  "checkout-variant": {"button_color": "green"}
}

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"
  }'

import requests

response = requests.post(
    "https://app.posthog.com/decide",
    json={
        "api_key": "phc_your_project_api_key",
        "distinct_id": "user_123"
    }
)

flags = response.json()["featureFlags"]
print(flags)  # {"new-dashboard": true, "beta-feature": false}

fetch('https://app.posthog.com/decide', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    api_key: 'phc_your_project_api_key',
    distinct_id: 'user_123'
  })
})
  .then(res => res.json())
  .then(data => {
    console.log(data.featureFlags);
  });

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": "user@company.com",
      "plan": "premium",
      "signup_date": "2024-01-15"
    }
  }'

import requests

response = requests.post(
    "https://app.posthog.com/decide",
    json={
        "api_key": "phc_your_project_api_key",
        "distinct_id": "user_123",
        "person_properties": {
            "email": "user@company.com",
            "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"
      }
    }
  }'

import requests

response = requests.post(
    "https://app.posthog.com/decide",
    json={
        "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"
  }'

import requests

response = requests.post(
    "https://app.posthog.com/decide",
    json={
        "api_key": "phc_your_project_api_key",
        "distinct_id": "user_123",
        "$anon_distinct_id": "anon_456"  # Previous anonymous ID
    }
)

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');

from posthog import Posthog

posthog = Posthog('phc_your_project_api_key')

# Boolean flag
if posthog.feature_enabled('new-dashboard', 'user_123'):
    # Show new dashboard
    pass

# Multivariate flag
variant = posthog.get_feature_flag('checkout-flow', 'user_123')

# With properties
if posthog.feature_enabled(
    'beta-feature',
    'user_123',
    person_properties={'plan': 'premium'}
):
    pass

use PostHog\PostHog;

PostHog::init('phc_your_project_api_key');

// Boolean flag
if (PostHog::isFeatureEnabled('new-dashboard', 'user_123')) {
    // Show new dashboard
}

// Multivariate flag
$variant = PostHog::getFeatureFlag('checkout-flow', 'user_123');

Overview

Events

Feature Flags

Cohorts

Insights

Evaluate Feature Flags

POST /decide

Request Body

Response

Examples

Basic Flag Evaluation

With Person Properties

With Group Properties

With Anonymous ID for Experience Continuity

Response Examples

Boolean Flags

Multivariate Flags with Payloads

With Errors

SDKs

​POST /decide

​Request Body

​Response

​Examples

​Basic Flag Evaluation

​With Person Properties

​With Group Properties

​With Anonymous ID for Experience Continuity

​Response Examples

​Boolean Flags

​Multivariate Flags with Payloads

​With Errors

​SDKs

POST /decide

Request Body

Response

Examples

Basic Flag Evaluation

With Person Properties

With Group Properties

With Anonymous ID for Experience Continuity

Response Examples

Boolean Flags

Multivariate Flags with Payloads

With Errors

SDKs