LaunchDarkly REST API
LaunchDarkly DocsSign in
HomeAPI ReferenceSDKsContext Plugin
Feature flags

List feature flags

GET
/api/v2/flags/{projectKey}

Get a list of all feature flags in the given project. You can include information specific to different environments by adding env query parameter. For example, setting env=production adds configuration details about your production environment to the response. You can also filter feature flags by tag with the tag query parameter.

Recommended use

This endpoint can return a large amount of information. We recommend using some or all of these query parameters to decrease response time and overall payload size: limit, env, query, and filter=creationDate.

Filtering flags

You can filter on certain fields using the filter query parameter. For example, setting filter=query:dark-mode,tags:beta+test matches flags with the string dark-mode in their key or name, ignoring case, which also have the tags beta and test.

The filter query parameter supports the following arguments:

Filter argumentDescriptionExample
applicationEvaluatedA string. It filters the list to flags that are evaluated in the application with the given key.filter=applicationEvaluated:com.launchdarkly.cafe
archived(deprecated) A boolean value. It filters the list to archived flags.Use filter=state:archived instead
contextKindsEvaluatedA +-separated list of context kind keys. It filters the list to flags which have been evaluated in the past 30 days for all of the context kinds in the list.filter=contextKindsEvaluated:user+application
codeReferences.maxAn integer value. Use 0 to return flags that do not have code references.filter=codeReferences.max:0
codeReferences.minAn integer value. Use 1 to return flags that do have code references.filter=codeReferences.min:1
creationDateAn object with an optional before field whose value is Unix time in milliseconds. It filters the list to flags created before the date.filter=creationDate:{"before":1690527600000}
evaluatedAn object that contains a key of after and a value in Unix time in milliseconds. It filters the list to all flags that have been evaluated since the time you specify, in the environment provided. This filter requires the filterEnv filter.filter=evaluated:{"after":1690527600000},filterEnv:production
filterEnvA valid environment key. You must use this field for filters that are environment-specific. If there are multiple environment-specific filters, you only need to include this field once.filter=evaluated:{"after": 1590768455282},filterEnv:production
guardedRolloutA string, one of any, monitoring, regressed, rolledBack, completed, archived. It filters the list to flags that are part of guarded rollouts.filter=guardedRollout:monitoring
hasExperimentA boolean value. It filters the list to flags that are used in an experiment.filter=hasExperiment:true
maintainerIdA valid member ID. It filters the list to flags that are maintained by this member.filter=maintainerId:12ab3c45de678910abc12345
maintainerTeamKeyA string. It filters the list to flags that are maintained by the team with this key.filter=maintainerTeamKey:example-team-key
queryA string. It filters the list to flags that include the specified string in their key or name. It is not case sensitive.filter=query:example
releasePipelineA release pipeline key. It filters the list to flags that are either currently active in the release pipeline or have completed the release pipeline.filter=releasePipeline:default-release-pipeline
stateA string, either live, deprecated, or archived. It filters the list to flags in this state.filter=state:archived
sdkAvailabilityA string, one of client, mobile, anyClient, server. Using client filters the list to flags whose client-side SDK availability is set to use the client-side ID. Using mobile filters to flags set to use the mobile key. Using anyClient filters to flags set to use either the client-side ID or the mobile key. Using server filters to flags set to use neither, that is, to flags only available in server-side SDKs.filter=sdkAvailability:client
tagsA +-separated list of tags. It filters the list to flags that have all of the tags in the list.filter=tags:beta+test
typeA string, either temporary or permanent. It filters the list to flags with the specified type.filter=type:permanent

The documented values for the filter query are prior to URL encoding. For example, the + in filter=tags:beta+test must be encoded to %2B.

By default, this endpoint returns all flags. You can page through the list with the limit parameter and by following the first, prev, next, and last links in the returned _links field. These links will not be present if the pages they refer to don't exist. For example, the first and prev links will be missing from the response on the first page.

Sorting flags

You can sort flags based on the following fields:

  • creationDate sorts by the creation date of the flag.
  • key sorts by the key of the flag.
  • maintainerId sorts by the flag maintainer.
  • name sorts by flag name.
  • tags sorts by tags.
  • targetingModifiedDate sorts by the date that the flag's targeting rules were last modified in a given environment. It must be used with env parameter and it can not be combined with any other sort. If multiple env values are provided, it will perform sort using the first one. For example, sort=-targetingModifiedDate&env=production&env=staging returns results sorted by targetingModifiedDate for the production environment.
  • type sorts by flag type

All fields are sorted in ascending order by default. To sort in descending order, prefix the field with a dash ( - ). For example, sort=-name sorts the response by flag name in descending order.

Expanding response

LaunchDarkly supports the expand query param to include additional fields in the response, with the following fields:

  • codeReferences includes code references for the feature flag
  • evaluation includes evaluation information within returned environments, including which context kinds the flag has been evaluated for in the past 30 days
  • migrationSettings includes migration settings information within the flag and within returned environments. These settings are only included for migration flags, that is, where purpose is migration.

For example, expand=evaluation includes the evaluation field in the response.

Migration flags

For migration flags, the cohort information is included in the rules property of a flag's response, and default cohort information is included in the fallthrough property of a flag's response. To learn more, read Migration Flags.

Authorization

ApiKey read, write
Authorization<token>

In: header

Scope: read, write

Path Parameters

projectKey*string

The project key

Formatstring

Query Parameters

env?string

Filter configurations by environment

Formatstring
tag?string

Filter feature flags by tag

Formatstring
limit?integer

The number of feature flags to return. Defaults to 20.

Formatint64
offset?integer

Where to start in the list. Use this with pagination. For example, an offset of 10 skips the first ten items and then returns the next items in the list, up to the query limit.

Formatint64
archived?boolean
Deprecated

Deprecated, use filter=archived:true instead. A boolean to filter the list to archived flags. When this is absent, only unarchived flags will be returned

summary?boolean

By default, flags do not include their lists of prerequisites, targets, or rules for each environment. Set summary=0 and include the env query parameter to include these fields for each flag returned.

filter?string

A comma-separated list of filters. Each filter is of the form field:value. Read the endpoint description for a full list of available filter fields.

Formatstring
sort?string

A comma-separated list of fields to sort by. Fields prefixed by a dash ( - ) sort in descending order. Read the endpoint description for a full list of available sort fields.

Formatstring
compare?boolean
Deprecated

Deprecated, unavailable in API version 20240415. A boolean to filter results by only flags that have differences between environments.

expand?string

A comma-separated list of fields to expand in the response. Supported fields are explained above.

Formatstring

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v2/flags/string"
{  "items": [    {      "name": "My Flag",      "kind": "boolean",      "description": "This flag controls the example widgets",      "key": "flag-key-123abc",      "_version": 1,      "creationDate": "1494437420312",      "includeInSnippet": true,      "clientSideAvailability": "{\"usingMobileKey\":true,\"usingEnvironmentId\":false}",      "variations": [        {          "_id": "e432f62b-55f6-49dd-a02f-eb24acf39d05",          "value": true        },        {          "_id": "a00bf58d-d252-476c-b915-15a74becacb4",          "value": false        }      ],      "temporary": true,      "tags": [        "example-tag"      ],      "_links": {        "parent": {          "href": "/api/v2/flags/my-project",          "type": "application/json"        },        "self": {          "href": "/api/v2/flags/my-project/my-flag",          "type": "application/json"        }      },      "maintainerId": "569f183514f4432160000007",      "_maintainer": {        "_links": {          "self": {            "href": "/api/v2/members/569f183514f4432160000007",            "type": "application/json"          }        },        "_id": "569f183514f4432160000007",        "firstName": "Ariel",        "lastName": "Flores",        "role": "admin",        "email": "ariel@acme.com"      },      "maintainerTeamKey": "team-1",      "_maintainerTeam": {        "key": "team-key-123abc",        "name": "Example team",        "_links": {          "parent": {            "href": "/api/v2/teams",            "type": "application/json"          },          "roles": {            "href": "/api/v2/teams/example-team/roles",            "type": "application/json"          },          "self": {            "href": "/api/v2/teams/example-team",            "type": "application/json"          }        }      },      "goalIds": [],      "experiments": "{\"baselineIdx\": 0,\"items\": []}",      "customProperties": "{\"jira.issues\":{\"name\":\"Jira issues\",\"value\":[\"is-123\",\"is-456\"]}}",      "archived": false,      "archivedDate": "1494437420312",      "deprecated": false,      "deprecatedDate": "1494437420312",      "defaults": "{\"onVariation\":0,\"offVariation\":1}",      "_purpose": "string",      "migrationSettings": {        "contextKind": "device",        "stageCount": 6      },      "stale": {        "readyForCodeRemoval": true,        "readyToArchive": true,        "cleanupId": "string"      },      "environments": {        "my-environment": {          "_environmentName": "My Environment",          "_site": {            "href": "/default/my-environment/features/client-side-flag",            "type": "text/html"          },          "_summary": {            "prerequisites": 0,            "variations": {              "0": {                "contextTargets": 1,                "isFallthrough": true,                "nullRules": 0,                "rules": 0,                "targets": 1              },              "1": {                "isOff": true,                "nullRules": 0,                "rules": 0,                "targets": 0              }            }          },          "archived": false,          "contextTargets": [            {              "contextKind": "device",              "values": [                "device-key-123abc"              ],              "variation": 0            }          ],          "fallthrough": {            "variation": 0          },          "lastModified": 1627071171347,          "offVariation": 1,          "on": false,          "prerequisites": [],          "rules": [],          "salt": "61eddeadbeef4da1facecafe3a60a397",          "sel": "810edeadbeef4844facecafe438f2999492",          "targets": [            {              "contextKind": "user",              "values": [                "user-key-123abc"              ],              "variation": 0            }          ],          "trackEvents": false,          "trackEventsFallthrough": false,          "version": 1        }      }    }  ],  "_links": {    "self": {      "href": "/api/v2/flags/default",      "type": "application/json"    }  },  "totalCount": 1,  "totalCountWithDifferences": 0}

Get feature flag status GET

Get the status for a particular feature flag.

Create a feature flag POST

Create a feature flag with the given name, key, and variations. <details> <summary>Click to expand instructions for <strong>creating a migration flag</strong></summary> ### Creating a migration flag When you create a migration flag, the variations are pre-determined based on the number of stages in the migration. To create a migration flag, omit the `variations` and `defaults` information. Instead, provide a `purpose` of `migration`, and `migrationSettings`. If you create a migration flag with six stages, `contextKind` is required. Otherwise, it should be omitted. Here's an example: ```json { "key": "flag-key-123", "purpose": "migration", "migrationSettings": { "stageCount": 6, "contextKind": "account" } } ``` To learn more, read [Migration Flags](https://launchdarkly.com/docs/home/flags/migration). </details>