User settings

LaunchDarkly's user settings API provides a picture of all feature flags and their current values for a specific user. This gives you instant visibility into how a particular user experiences your site or application. To learn more, read Viewing and managing users.

You can also use the user settings API to assign a user to a specific variation for any feature flag.

List flag settings for user

Get the current flag settings for a given user.

The _value is the flag variation that the user receives. The setting indicates whether you've explicitly targeted a user to receive a particular variation. For example, if you have turned off a feature flag for a user, this setting will be false. The example response indicates that the user Abbie_Braun has the sort.order flag enabled and the alternate.page flag disabled, and that the user has not been explicitly targeted to receive a particular variation.

Request
path Parameters
projectKey
required
string <string>

The project key

environmentKey
required
string <string>

The environment key

userKey
required
string <string>

The user key

Responses
200

User flag settings collection response

400

Invalid request

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

429

Rate limited

get/api/v2/users/{projectKey}/{environmentKey}/{userKey}/flags
Request samples
Response samples
application/json
{
  • "items": {
    },
  • "_links": {
    }
}

Get flag setting for user

Get a single flag setting for a user by flag key.

The _value is the flag variation that the user receives. The setting indicates whether you've explicitly targeted a user to receive a particular variation. For example, if you have turned off a feature flag for a user, this setting will be false. The example response indicates that the user Abbie_Braun has the sort.order flag enabled.

Request
path Parameters
projectKey
required
string <string>

The project key

environmentKey
required
string <string>

The environment key

userKey
required
string <string>

The user key

featureFlagKey
required
string <string>

The feature flag key

Responses
200

User flag settings response

400

Invalid request

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

429

Rate limited

get/api/v2/users/{projectKey}/{environmentKey}/{userKey}/flags/{featureFlagKey}
Request samples
Response samples
application/json
{
  • "_links": {
    },
  • "_value": "true",
  • "setting": "null",
  • "reason": {
    }
}

Update flag settings for user

Enable or disable a feature flag for a user based on their key.

Omitting the setting attribute from the request body, or including a setting of null, erases the current setting for a user.

If you previously patched the flag, and the patch included the user's data, LaunchDarkly continues to use that data. If LaunchDarkly has never encountered the user's key before, it calculates the flag values based on the user key alone.

Request
path Parameters
projectKey
required
string <string>

The project key

environmentKey
required
string <string>

The environment key

userKey
required
string <string>

The user key

featureFlagKey
required
string <string>

The feature flag key

Request Body schema: application/json
setting
any

The variation value to set for the user. Must match the flag's variation type.

comment
string

Optional comment describing the change

Responses
204

Action succeeded

400

Invalid request

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

429

Rate limited

put/api/v2/users/{projectKey}/{environmentKey}/{userKey}/flags/{featureFlagKey}
Request samples
application/json
{
  • "setting": "existing_variation_value_to_use",
  • "comment": "make sure this user experiences a specific variation"
}
Response samples
application/json
{
  • "code": "invalid_request",
  • "message": "Invalid request body"
}

Get expiring dates on flags for user

Get a list of flags for which the given user is scheduled for removal.

Request
path Parameters
projectKey
required
string <string>

The project key

userKey
required
string <string>

The user key

environmentKey
required
string <string>

The environment key

Responses
200

Expiring user target response

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

429

Rate limited

get/api/v2/users/{projectKey}/{userKey}/expiring-user-targets/{environmentKey}
Request samples
Response samples
application/json
{
  • "items": [
    ],
  • "_links": {
    }
}

Update expiring user target for flags

Schedule the specified user for removal from individual targeting on one or more flags. The user must already be individually targeted for each flag.

You can add, update, or remove a scheduled removal date. You can only schedule a user for removal on a single variation per flag.

This request only supports semantic patches. To make a semantic patch request, you must append domain-model=launchdarkly.semanticpatch to your Content-Type header. To learn more, read Updates using semantic patch.

Instructions

addExpireUserTargetDate

Adds a date and time that LaunchDarkly will remove the user from the flag's individual targeting.

Parameters
  • value: The time, in Unix milliseconds, when LaunchDarkly should remove the user from individual targeting for this flag.

updateExpireUserTargetDate

Updates the date and time that LaunchDarkly will remove the user from the flag's individual targeting.

Parameters
  • value: The time, in Unix milliseconds, when LaunchDarkly should remove the user from individual targeting for this flag.
  • version: The version of the flag variation to update. You can retrieve this by making a GET request for the flag.

removeExpireUserTargetDate

Removes the scheduled removal of the user from the flag's individual targeting. The user will remain part of the flag's individual targeting until explicitly removed, or until another removal is scheduled.

Request
path Parameters
projectKey
required
string <string>

The project key

userKey
required
string <string>

The user key

environmentKey
required
string <string>

The environment key

Request Body schema: application/json
comment
string

Optional comment describing the change

required
Array of objects (instructionUserRequest)

The instructions to perform when updating

Responses
200

Expiring user target response

400

Invalid request

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

429

Rate limited

patch/api/v2/users/{projectKey}/{userKey}/expiring-user-targets/{environmentKey}
Request samples
application/json
{
  • "comment": "optional comment",
  • "instructions": [
    ]
}
Response samples
application/json
{
  • "items": [
    ],
  • "_links": {
    },
  • "totalInstructions": 1,
  • "successfulInstructions": 1,
  • "failedInstructions": 0,
  • "errors": [
    ]
}