--- title: List feature flag change history description: Returns the organization's feature flag change events, newest first. breadcrumbs: Docs > API > List feature flag change history --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # List feature flag change history ## v2 (latest) | Datadog site | API endpoint | | ----------------- | -------------------------------------------------------------- | | app.datadoghq.com | GET https://api.datadoghq.com/api/v2/feature-flags/history | | us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/feature-flags/history | | us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/feature-flags/history | | app.datadoghq.eu | GET https://api.datadoghq.eu/api/v2/feature-flags/history | | ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/feature-flags/history | | ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/feature-flags/history | | uk1.datadoghq.com | GET https://api.uk1.datadoghq.com/api/v2/feature-flags/history | | app.ddog-gov.com | GET https://api.ddog-gov.com/api/v2/feature-flags/history | | us2.ddog-gov.com | GET https://api.us2.ddog-gov.com/api/v2/feature-flags/history | ### Overview Returns the organization's feature flag change events, newest first. Each event includes a readable description of the change. All filters are optional, and events must match every filter you set. Without a date range, the whole history is listed. Results are paginated with `page[limit]` and `page[offset]`; follow `links.next` to read further back. This endpoint requires the `feature_flag_config_read` permission. OAuth apps require the `feature_flag_config_read` authorization [scope](https://docs.datadoghq.com/api/latest/scopes.md#feature-flags) to access this endpoint. ### Arguments #### Query Strings | Field | Type | Description | | ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | start_date | string | Only include changes made after this time, for example `2026-01-01T00:00:00Z`. The bound is exclusive, so a change made exactly at this time is not included. Omit for no lower bound. | | end_date | string | Only include changes made before this time, for example `2026-02-01T00:00:00Z`. The bound is exclusive, so a change made exactly at this time is not included. Omit for no upper bound. Must be after `start_date` when both are set. | | teams | array | Only include changes to flags that belong to at least one of these teams. Use team handles without the `team:` prefix, as repeated parameters, such as `teams=checkout&teams=payments`. Handles from `teams` and `team:` values from `tags` are treated as one set. Handles that are empty, have surrounding white space, or include the `team:` prefix return a `400 Bad Request` error. | | tags | array | Only include changes to flags that have all of these exact tags, as repeated parameters, such as `tags=env:prod&tags=tier:1`. Values of the form `team:` match any selected team and are combined with `teams`. Empty values are ignored. | | feature_flag_id | string | Only include changes to this feature flag. | | environment_id | string | Only include changes to this environment. Changes to the flag itself, which have no environment, are always included. | | include_suggestion_events | boolean | Also include review events for change requests that needed approval: rejected requests and requests still pending review. Applies only to organizations with flag approvals enabled. Default: `false`. | | page[limit] | integer | Maximum number of events to return. Defaults to `25`. Values above `50` return `50` events. Non-positive or empty values use the default. A non-integer value returns a `400 Bad Request` error. Default: `25`. | | page[offset] | integer | Number of matching events to skip before returning results. Defaults to `0`. Negative or empty values are set to `0`. A non-integer value returns a `400 Bad Request` error. Default: `0`. | ### Response {% tabs %} {% tab label="200" %} OK {% tabs %} {% tab label="Model" %} Response containing feature flag change events, newest first. | Parent field | Field | Type | Description | | ----------------- | ----------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | data [*required*] | [object] | The change events. | | data | attributes [*required*] | object | Attributes of a feature flag change event. | | attributes | action [*required*] | enum | The kind of change. Allowed enum values: `created`, `updated`, `deleted`, `archived`, `unarchived`, `scheduled`, `started`, `paused`, `unpaused`, `stopped`. | | attributes | change_metadata | string | Additional details about the change, as a JSON-encoded string. | | attributes | creation_source | enum | Where the change was made: `UI` for the Datadog app, or `MCP` for a Model Context Protocol (MCP) client. Allowed enum values: `UI`, `MCP`. | | attributes | description | string | A readable sentence describing the change, as shown on the flag history page and in the Action column of the CSV export. | | attributes | environment | object | The environment the change applies to. Null for a change to the flag itself rather than to one environment. | | environment | id [*required*] | uuid | The ID of the environment. | | environment | is_production [*required*] | boolean | Whether the environment is a production environment. | | environment | name [*required*] | string | The name of the environment. | | attributes | feature_flag [*required*] | object | The feature flag the change applies to. | | feature_flag | id [*required*] | uuid | The ID of the feature flag. | | feature_flag | key [*required*] | string | The key of the feature flag. | | feature_flag | name [*required*] | string | The name of the feature flag. | | attributes | new_value | string | The value after the change, serialized as a string. | | attributes | previous_value | string | The value before the change, serialized as a string. | | attributes | property [*required*] | enum | The part of the feature flag the change applies to. Allowed enum values: `FLAG`, `FLAG_NAME`, `FLAG_DESCRIPTION`, `JSON_SCHEMA`, `DISTRIBUTION_CHANNEL`, `REQUIRE_APPROVAL`, `VARIANT`, `VARIANT_NAME`, `VARIANT_VALUE`, `ALLOCATIONS`, `ROLLOUT`, `ENVIRONMENT_STATUS`, `DEFAULT_VARIANT`, `OVERRIDE_VARIANT`, `STALENESS_STATUS`, `SAVED_FILTER`. | | attributes | suggestion_review | object | Review details of a change request that needed approval. Present on review events, which `include_suggestion_events` adds. Also present on a change that an approved change request applied, even when `include_suggestion_events` is `false`. | | suggestion_review | lifecycle_status [*required*] | enum | Where the change request is in its lifecycle. Allowed enum values: `pending`, `approved`, `applied`, `rejected`, `discarded`. | | suggestion_review | requester_comment | string | The comment left by the person who requested the change. | | suggestion_review | reviewer_comment | string | The comment left by the reviewer. | | suggestion_review | status [*required*] | enum | The review status of the change request. Allowed enum values: `pending`, `approved`, `rejected`. | | suggestion_review | suggestion_created_by | string | The ID of the user who requested the change. | | attributes | timestamp [*required*] | date-time | When the change was made. | | attributes | user_id | string | The ID of the user who made the change. Null when no user made the change. | | attributes | version_number [*required*] | int64 | The version of the feature flag the change produced. | | data | id [*required*] | uuid | The ID of the change event. | | data | type [*required*] | enum | The resource type. Allowed enum values: `change-events`. | | | links | object | Pagination links. Follow `next` with the same authentication to retrieve the next page. Links use `page[limit]` and `page[offset]` and preserve the filters. Navigation links are omitted when not applicable. | | links | first | string | Link to the first page. | | links | last | string | Link to the last page. | | links | next | string | Link to the next page, when available. | | links | prev | string | Link to the previous page, when available. | | links | self | string | Link to the current page. | | | meta | object | Pagination metadata for feature flag change history. | | meta | page | object | Pagination metadata for feature flag change history responses. | | page | first_offset | int64 | Offset of the first page. | | page | last_offset | int64 | Offset of the last page. | | page | limit | int64 | Maximum number of events returned on this page. | | page | next_offset | int64 | Offset of the next page, or null when there is no next page. | | page | offset | int64 | Number of matching events skipped before this page. | | page | prev_offset | int64 | Offset of the previous page, or null when there is no previous page. | | page | total | int64 | Total number of events matching the filters, independent of the page size. It counts experiment proposals that you cannot read, which are left out of the pages, so a page can hold fewer events than `limit`. | | page | type | string | The pagination method. Always `offset_limit`. | {% /tab %} {% tab label="Example" %} ```json { "data": [ { "attributes": { "action": "updated", "change_metadata": "{\"variant_key\": \"control\"}", "creation_source": "UI", "description": "Changed flag name from \"Mobile Feature Rollout\" to \"Mobile Feature Toggle\".", "environment": { "id": "550e8400-e29b-41d4-a716-446655440001", "is_production": true, "name": "Production" }, "feature_flag": { "id": "550e8400-e29b-41d4-a716-446655440000", "key": "mobile-feature-toggle", "name": "Mobile Feature Toggle" }, "new_value": "Mobile Feature Toggle", "previous_value": "Mobile Feature Rollout", "property": "FLAG_NAME", "suggestion_review": { "lifecycle_status": "rejected", "requester_comment": "Ready for production.", "reviewer_comment": "Roll out to staging first.", "status": "rejected", "suggestion_created_by": "00000000-0000-0000-0000-000000000001" }, "timestamp": "2023-10-02T14:30:00Z", "user_id": "00000000-0000-0000-0000-000000000001", "version_number": 3 }, "id": "550e8400-e29b-41d4-a716-446655440005", "type": "change-events" } ], "links": { "first": "https://api.datadoghq.com/api/v2/feature-flags?page%5Blimit%5D=25&page%5Boffset%5D=0", "last": "https://api.datadoghq.com/api/v2/feature-flags?page%5Blimit%5D=25&page%5Boffset%5D=75", "next": "https://api.datadoghq.com/api/v2/feature-flags?page%5Blimit%5D=25&page%5Boffset%5D=25", "prev": "https://api.datadoghq.com/api/v2/feature-flags?page%5Blimit%5D=25&page%5Boffset%5D=0", "self": "https://api.datadoghq.com/api/v2/feature-flags?page%5Blimit%5D=25&page%5Boffset%5D=0" }, "meta": { "page": { "first_offset": 0, "last_offset": 75, "limit": 25, "next_offset": 25, "offset": 0, "prev_offset": 0, "total": 100, "type": "offset_limit" } } } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="400" %} Bad Request {% tabs %} {% tab label="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------- | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="403" %} Forbidden {% tabs %} {% tab label="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------- | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="429" %} Too many requests {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% /tabs %} ### Code Example {% tabs %} {% tab label="Curl" %} ```bash # Set your Datadog site and credentials export DD_SITE="datadoghq.com" # Or us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, uk1.datadoghq.com, ddog-gov.com, us2.ddog-gov.com # Use a Personal Access Token or Service Access Token export DD_BEARER_TOKEN="" curl -X GET "https://api.${DD_SITE}/api/v2/feature-flags/history" \ -H "Accept: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" ``` {% /tab %} {% /tabs %}