references/adding-feature-flag-code.md · 96000
(backward compatibility)
Runtime detection
Evaluation runtime (server vs. client) is automatically detected based on your request headers and user-agent. This determines which flags are available based on their runtime setting (server-only, client-only, or all).
How runtime is detected:
-
User-Agent patterns - The system analyzes the User-Agent header:
- Client-side patterns:
Mozilla/,Chrome/,Safari/,Firefox/,Edge/(browsers), or mobile SDKs likeposthog-android/,posthog-ios/,posthog-react-native/,posthog-flutter/ - Server-side patterns:
posthog-python/,posthog-ruby/,posthog-php/,posthog-java/,posthog-go/,posthog-node/,posthog-dotnet/,posthog-elixir/,python-requests/,curl/
- Client-side patterns:
-
Browser-specific headers - Presence of these headers indicates client-side:
OriginheaderRefererheaderSec-Fetch-ModeheaderSec-Fetch-Siteheader
-
Default behavior - If runtime can't be determined, the system includes flags with no runtime requirement and those set to "all"
Examples of runtime detection:
JavaScript
PostHog AI
// Browser fetch - Detected as CLIENT runtime
// Will receive: client-only flags + "all" flags
// Won't receive: server-only flags
const response = await fetch("https://us.i.posthog.com/flags?v=2", {
method: "POST",
headers: {
"Content-Type": "application/json",
// Browser automatically adds Origin, Referer, Sec-Fetch-* headers
},
body: JSON.stringify({
api_key: "<ph_project_token>",
distinct_id: "user-id"
})
});
Python
PostHog AI
# Python requests - Detected as SERVER runtime
# Will receive: server-only flags + "all" flags
# Won't receive: client-only flags
import requests
response = requests.post(
"https://us.i.posthog.com/flags?v=2",
json={
"api_key": "<ph_project_token>",
"distinct_id": "user-id"
}
# python-requests/ in User-Agent indicates server-side
)
Terminal
PostHog AI
# curl - Detected as SERVER runtime
# Will receive: server-only flags + "all" flags
# Won't receive: client-only flags
curl -v -L --header "Content-Type: application/json" -d '{
"api_key": "<ph_project_token>",
"distinct_id": "user-id"
}' "https://us.i.posthog.com/flags?v=2"
# curl/ in User-Agent indicates server-side
JavaScript
PostHog AI
// Node.js with custom User-Agent - Control runtime detection
const response = await fetch("https://us.i.posthog.com/flags?v=2", {
method: "POST",
headers: {
"Content-Type": "application/json",
"User-Agent": "posthog-node/3.0.0" // Explicitly indicates server-side
},
body: JSON.stringify({
api_key: "<ph_project_token>",
distinct_id: "user-id"
})
});
Combining evaluation context tags and runtime filtering
Both features work together as sequential filters:
JavaScript
PostHog AI
// Example: Production web client
const response = await fetch("https://us.i.posthog.com/flags?v=2", {
method: "POST",
headers: {
"Content-Type": "application/json",
// Browser headers will trigger client runtime detection
},
body: JSON.stringify({
api_key: "<ph_project_token>",
distinct_id: "user-id",
evaluation_contexts: ["production", "web"]
})
});
// This request will only receive flags that:
// 1. Have runtime set to "client" OR "all" (due to browser headers)
// AND
// 2. Have evaluation context tags matching "production" OR "web" (or no tags)
// Note: You can also use the legacy "evaluation_environments" parameter
This allows precise control over which flags are evaluated in different contexts, helping optimize costs and improve security by ensuring flags only evaluate where intended.
Response
The response varies depending on whether you include the config=true query parameter:
Basic response (/flags?v=2)
Use this endpoint when you only need to evaluate feature flags. It returns a response with just the flag evaluation results.
Note: If a feature flag is associated with an experiment that has a holdout group, users in the holdout receive a variant value in the format
holdout-{holdout_id}(e.g.,holdout-727). You can detect holdout users by checking if the variant starts withholdout-.
JSON
PostHog AI
{
"flags": {
"my-awesome-flag": {
"key": "my-awesome-flag",
"enabled": true,
"reason": {
"code": "condition_match",
"condition_index": 0,
"description": "Condition set 1 matched"
},
"metadata": {
"id": 1,
"version": 1,
"payload": "{\"example\": \"json\", \"payload\": \"value\"}"
}
},
"my-multivariate-flag" :{
"key":"my-multivariate-flag",
"enabled": true,
"variant": "some-string-value",
"reason": {
"code": "condition_match",
"condition_index": 1,
"description": "Condition set 2 matched"
},
"metadata": {
"id": 2,
"version": 42,
}
},
"flag-thats-not-on": {
"key": "flag-thats-not-on",
"enabled": false,
"reason": {
"code": "no_condition_match",
"condition_index": 0,
"description": "No condition sets matched"
},
"metadata": {
"id": 3,
"version": 1
}
}
},
"errorsWhileComputingFlags": false,
"requestId": "550e8400-e29b-41d4-a716-446655440000"
}
Full response with configuration (/flags?v=2&config=true)
Use this endpoint when you need both feature flag evaluation and PostHog configuration information (useful for client-side SDKs that need to initialize PostHog):
JSON
PostHog AI
{
"config": {
"enable_collect_everything": true
},
"toolbarParams": {},
"errorsWhileComputingFlags": false,
"isAuthenticated": false,
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"supportedCompression": [
"gzip",
"lz64"
],
"flags": {
"my-awesome-flag": {
"key": "my-awesome-flag",
"enabled": true,
"reason": {
"code": "condition_match",
"condition_index": 0,
"description": "Condition set 1 matched"
},
"metadata": {
"id": 1,
"version": 1,
"payload": "{\"example\": \"json\", \"payload\": \"value\"}"
}
},
"my-multivariate-flag" :{
"key":"my-multivariate-flag",
"enabled": true,
"variant": "some-string-value",
"reason": {
"code": "condition_match",
"condition_index": 1,
"description": "Condition set 2 matched"
},
"metadata": {
"id": 2,
"version": 42,
}
},
"flag-thats-not-on": {
"key": "flag-thats-not-on",
"enabled": false,
"reason": {
"code": "no_condition_match",
"condition_index": 0,
"description": "No condition sets matched"
},
"metadata": {
"id": 3,
"version": 1
}
}
}
}
Note:
errorsWhileComputingFlagswill returntrueif we didn't manage to compute some flags (for example, if there's an ongoing incident involving flag evaluation).This enables partial updates to currently active flags in your clients.
Quota limiting
If your organization exceeds its feature flag quota, the /flags endpoint will return a modified response with quotaLimited.
For basic response (/flags?v=2):
JSON
PostHog AI
{
"flags": {},
"errorsWhileComputingFlags": false,
"quotaLimited": ["feature_flags"],
"requestId": "d4d89b14-9619-4627-adf2-01b761691c2e"
}
For full response with configuration (/flags?v=2&config=true):
JSON
PostHog AI
{
"config": {
"enable_collect_everything": true
},
"toolbarParams": {},
"isAuthenticated": false,
"supportedCompression": [
"gzip",
"lz64"
],
"flags": {},
"errorsWhileComputingFlags": false,
"quotaLimited": ["feature_flags"],
"requestId": "d4d89b14-9619-4627-adf2-01b761691c2e"
// ... other fields, not relevant to feature flags
}
When you receive a response with quotaLimited containing "feature_flags", it means:
- Your feature flag evaluations have been temporarily paused because you've exceeded your feature flag quota
- If you want to continue evaluating feature flags, you can increase your quota in your billing settings under Feature flags & Experiments or contact support
Step 2: Include feature flag information when capturing events
If you want use your feature flag to breakdown or filter events in your insights, you'll need to include feature flag information in those events. This ensures that the feature flag value is attributed correctly to the event.
Note: This step is only required for events captured using our server-side SDKs or API.
To do this, include the $feature/feature_flag_name property in your event:
PostHog AI
Terminal
curl -v -L --header "Content-Type: application/json" -d ' {
"api_key": "<ph_project_token>",
"event": "your_event_name",
"distinct_id": "distinct_id_of_your_user",
"properties": {
"$feature/feature-flag-key": "variant-key" # Replace feature-flag-key with your flag key. Replace 'variant-key' with the key of your variant
}
}' https://us.i.posthog.com/i/v0/e/
Python
import requests
import json
url = "https://us.i.posthog.com/i/v0/e/"
headers = {
"Content-Type": "application/json"
}
payload = {
"api_key": "<ph_project_token>",
"event": "your_event_name",
"distinct_id": "distinct_id_of_your_user,
"properties": {
"$feature/feature-flag-key": "variant-key" # Replace feature-flag-key with your flag key. Replace 'variant-key' with the key of your variant
}
}
response = requests.post(url, headers=headers, data=json.dumps(payload))
print(response)
Step 3: Send a $feature_flag_called event
To track usage of your feature flag and view related analytics in PostHog, submit the $feature_flag_called event whenever you check a feature flag value in your code.
You need to include two properties with this event:
$feature_flag_response: This is the name of the variant the user has been assigned to e.g., "control" or "test"$feature_flag: This is the key of the feature flag in your experiment.
PostHog AI
Terminal
curl -v -L --header "Content-Type: application/json" -d ' {
"api_key": "<ph_project_token>",
"event": "$feature_flag_called",
"distinct_id": "distinct_id_of_your_user",
"properties": {
"$feature_flag": "feature-flag-key",
"$feature_flag_response": "variant-name"
}
}' https://us.i.posthog.com/i/v0/e/
Python
import requests
import json
url = "https://us.i.posthog.com/i/v0/e/"
headers = {
"Content-Type": "application/json"
}
payload = {
"api_key": "<ph_project_token>",
"event": "feature_flag_called",
"distinct_id": "distinct_id_of_your_user,
"properties": {
"$feature_flag": "feature-flag-key",
"$feature_flag_response": "variant-name"
}
}
response = requests.post(url, headers=headers, data=json.dumps(payload))
print(response)
Advanced: Overriding server properties
Sometimes, you may want to evaluate feature flags using person properties, groups, or group properties that haven't been ingested yet, or were set incorrectly earlier.
You can provide properties to evaluate the flag with by using the person properties, groups, and group properties arguments. PostHog will then use these values to evaluate the flag, instead of any properties currently stored on your PostHog server.
For example:
PostHog AI
Terminal
curl -v -L --header "Content-Type: application/json" -d ' {
"api_key": "<ph_project_token>",
"distinct_id": "distinct_id_of_your_user",
"groups" : { # Required only for group-based feature flags
"group_type": "group_id" # Replace "group_type" with the name of your group type. Replace "group_id" with the id of your group.
},
"person_properties": {"<personProp1>": "<personVal1>"}, # Optional. Include any properties used to calculate the value of the feature flag.
"group_properties": {"group type": {"<groupProp1>":"<groupVal1>"}} # Optional. Include any properties used to calculate the value of the feature flag.
}' https://us.i.posthog.com/flags?v=2
Python
import requests
import json
url = "https://us.i.posthog.com/flags?v=2"
headers = {
"Content-Type": "application/json"
}
payload = {
"api_key": "<ph_project_token>",
"distinct_id": "distinct_id_of_your_user",
"groups" : { # Required only for group-based feature flags
"group_type": "group_id" # Replace "group_type" with the name of your group type. Replace "group_id" with the id of your group.
},
"person_properties": {"<personProp1>": "<personVal1>"}, # Optional. Include any properties used to calculate the value of the feature flag.
"group_properties": {"group type": {"<groupProp1>":"<groupVal1>"}} # Optional. Include any properties used to calculate the value of the feature flag.
}
response = requests.post(url, headers=headers, data=json.dumps(payload))
print(response.json())
Overriding GeoIP properties
By default, a user's GeoIP properties are set using the IP address they use to capture events on the frontend. You may want to override the these properties when evaluating feature flags. A common reason to do this is when you're not using PostHog on your frontend, so the user has no GeoIP properties.
To override the GeoIP properties used to evaluate a feature flag, provide an IP address in the HTTP_X_FORWARDED_FOR when making your /flags request:
PostHog AI
Terminal
curl -v -L \
--header "Content-Type: application/json" \
--header "HTTP_X_FORWARDED_FOR: the_client_ip_address_to_use " \
-d ' {
"api_key": "<ph_project_token>",
"distinct_id": "distinct_id_of_your_user"
}' https://us.i.posthog.com/flags?v=2
Python
import requests
import json
url = "https://us.i.posthog.com/flags?v=2"
headers = {
"Content-Type": "application/json",
"HTTP_X_FORWARDED_FOR": "the_client_ip_address_to_use"
}
payload = {
"api_key": "<ph_project_token>",
"distinct_id": "distinct_id_of_your_user"
}
response = requests.post(url, headers=headers, data=json.dumps(payload))
print(response.json())
The list of properties that this overrides:
$geoip_city_name$geoip_country_name$geoip_country_code$geoip_continent_name$geoip_continent_code$geoip_postal_code$geoip_time_zone
Community questions
Ask a question
Was this page useful?
HelpfulCould be better