--- title: List experiments description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: Docs > API Reference > Experiments --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). {% callout %} # Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com {% alert level="danger" %} This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). ({% placeholder "user-datadog-site-name" /%}). {% /alert %} {% /callout %} # List experiments{% #list-experiments %} {% tab title="v2" %} | Datadog site | API endpoint | | ----------------- | ---------------------------------------------------- | | ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/experiments | | ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/experiments | | app.datadoghq.eu | GET https://api.datadoghq.eu/api/v2/experiments | | app.ddog-gov.com | GET https://api.ddog-gov.com/api/v2/experiments | | us2.ddog-gov.com | GET https://api.us2.ddog-gov.com/api/v2/experiments | | uk1.datadoghq.com | GET https://api.uk1.datadoghq.com/api/v2/experiments | | app.datadoghq.com | GET https://api.datadoghq.com/api/v2/experiments | | us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/experiments | | us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/experiments | ### Overview List experiments. Returns a paginated list of experiments and their structured metadata for the organization. Supports filtering and pagination. Use Get experiment for variants, decision metrics, traffic exposure, and assignment configuration. This endpoint requires the `product_analytics_experiments_read` permission. OAuth apps require the `product_analytics_experiments_read` authorization [scope](https://docs.datadoghq.com/api/latest/scopes.md#experiments) to access this endpoint. ### Arguments #### Query Strings | Name | Type | Description | | ---------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | concluded_since | string | Return only experiments concluded at or after this RFC3339 timestamp. Inclusive, and excludes experiments that have not concluded. | | created_since | string | Return only experiments created at or after this RFC3339 timestamp. Inclusive. | | page[limit] | integer | Maximum number of results to return. Defaults to 25 when omitted, and is capped at 50 (larger values are clamped to 50). The response includes meta.page (with total) and pagination links. | | page[offset] | integer | Number of results to skip for pagination. Defaults to 0 when omitted. | | protocol_id | array | Filter by protocol UUID. Repeat this parameter to supply several IDs. An experiment matches if it uses any listed protocol. | | results_updated_before | string | Return only experiments whose results_last_updated is before this RFC3339 timestamp. results_last_updated is the later of the latest successful run completion and the latest stored result refresh. Exclusive, and excludes experiments without successful results. | | results_updated_since | string | Return only experiments whose results_last_updated is at or after this RFC3339 timestamp. results_last_updated is the later of the latest successful run completion and the latest stored result refresh. Inclusive, and excludes experiments without successful results. This filter does not include all metadata edits or deletions. | | search | string | Find experiments whose names contain the search text, regardless of case. | | sort | string | Sort fields: name, created_at, or updated_at. Use a comma-separated list in priority order, for example name,-created_at. Prefix each field with `-` for descending. Defaults to created_at descending. | | status | array | Filter by experiment status. Accepted values are DRAFT, SCHEDULED, IN_PROGRESS, READY_FOR_DECISION, DECISION_MADE, and CANCELLED. Repeat this parameter to select several statuses, for example `status=IN_PROGRESS&status=READY_FOR_DECISION`. | | tags | array | Filter by tag name. Repeat this parameter to supply several tags. An experiment matches if it has at least one listed tag. | ### Response {% tab title="200" %} OK {% tab title="Model" %} Response containing a page of experiment summaries. | Parent field | Field | Type | Description | | ------------------- | --------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | data [*required*] | [object] | Experiment summaries in the current page. | | data | attributes | object | Summary fields for an experiment returned in a list. | | attributes | assignments_end_date | date-time | End of the window used to read experiment assignments. | | attributes | assignments_start_date | date-time | Start of the window used to read experiment assignments. | | attributes | concluded_at | date-time | Time when the experiment was concluded. | | attributes | conclusion | object | Outcome and supporting text recorded when the experiment is concluded. | | conclusion | decision_reason | string | Reason for the recorded decision. | | conclusion | outcome | enum | Recorded experiment outcome. Allowed enum values: `POSITIVE,NEGATIVE,NEUTRAL,INCONCLUSIVE,MISCONFIGURED,UNKNOWN` | | conclusion | summary | string | Summary of the experiment conclusion. | | attributes | created_at | date-time | Time when the experiment was created. | | attributes | events_end_date | date-time | End of the window used to read metric events. | | attributes | events_start_date | date-time | Start of the window used to read metric events. | | attributes | experiment_type | string | Kind of experiment. STANDARD is an ordinary experiment. Other values, such as CANARY and HOLDOUT, identify experiments owned by another workflow. New kinds may be added; treat unknown values as non-standard. | | attributes | hypothesis | string | Expected effect that the experiment is designed to test. | | attributes | migration_metadata | | Metadata associated with migration of this resource. | | attributes | name | string | Display name of the experiment. | | attributes | pipeline_table_suffix | string | Suffix used for the experiment tables in the analysis pipeline. | | attributes | protocol_id | string | Identifier of the protocol associated with the experiment. | | attributes | related_links | [object] | External links associated with the experiment. | | related_links | id | string | Link ID. Omit it when adding a link. | | related_links | title | string | Optional display title. | | related_links | url [*required*] | string | Absolute URL. | | attributes | results_last_updated | date-time | Time when the experiment results were last updated. | | attributes | status | enum | Current stage in the experiment lifecycle. Allowed enum values: `DRAFT,SCHEDULED,IN_PROGRESS,READY_FOR_DECISION,DECISION_MADE,CANCELLED,UNKNOWN` | | attributes | structured_metadata | [object] | Custom metadata fields and their values for the experiment. | | structured_metadata | enum_values | [string] | Selected values for an enumerated metadata field. | | structured_metadata | field_display_name | string | Display name of the metadata field. | | structured_metadata | field_key [*required*] | string | Key that identifies the metadata field. | | structured_metadata | field_type | enum | Type of value stored in the structured metadata field. Allowed enum values: `FREETEXT,ENUM` | | structured_metadata | freetext_value | string | Text value for a free-text metadata field. | | attributes | subject_type_id | string | Identifier of the subject type used for experiment assignments. | | attributes | summary | string | Free-form summary of the experiment. | | attributes | tags | [string] | Tag names associated with the experiment. | | attributes | teams | [string] | Team handles associated with the experiment. | | attributes | updated_at | date-time | Time when the experiment was last updated. | | data | id [*required*] | uuid | Identifier of the experiment. | | data | type [*required*] | enum | Experiments resource type. Allowed enum values: `experiments` | | | links | object | Links for navigating a paginated result set. | | links | first | string | URL of the first page of results. | | links | last | string | URL of the last page of results. | | links | next | string | URL of the next page of results. | | links | prev | string | URL of the previous page of results. | | links | self | string | URL of the current page of results. | | | meta | object | Pagination information for a list response. | | meta | page | object | Result counts and offsets for a page of results. | | page | first_offset | int64 | Offset of the first page of results. | | page | last_offset | int64 | Offset of the last page of results. | | page | limit | int64 | Maximum number of results returned in one page. | | page | next_offset | int64 | Offset of the next page of results. | | page | offset | int64 | Number of results skipped before this page. | | page | prev_offset | int64 | Offset of the previous page of results. | | page | total | int64 | Total number of matching results across all pages. | | page | type | string | Pagination method used for this result set. | {% /tab %} {% tab title="Example" %} ```json { "data": [ { "attributes": { "assignments_end_date": "2026-08-15T00:00:00Z", "assignments_start_date": "2026-08-01T00:00:00Z", "concluded_at": "2026-08-05T09:30:00Z", "conclusion": { "decision_reason": "The primary metric improved without material regressions", "outcome": "POSITIVE", "summary": "The treatment improved conversion" }, "created_at": "2026-08-01T12:00:00Z", "events_end_date": "2026-08-22T00:00:00Z", "events_start_date": "2026-08-01T00:00:00Z", "experiment_type": "STANDARD", "hypothesis": "A clearer checkout button increases purchase conversion", "name": "Checkout button test", "pipeline_table_suffix": "a1b2c3d4", "protocol_id": "e4d5f6a7-0000-0000-0000-000000000000", "related_links": [ { "id": "d1d2d3d4-0000-0000-0000-000000000000", "title": "Experiment design", "url": "https://docs.example.com/checkout-experiment" } ], "results_last_updated": "2026-08-05T09:25:00Z", "status": "DECISION_MADE", "structured_metadata": [ { "enum_values": [ "beta" ], "field_display_name": "Launch stage", "field_key": "launch_stage", "field_type": "ENUM" }, { "field_display_name": "Notes", "field_key": "notes", "field_type": "FREETEXT", "freetext_value": "Checkout redesign" } ], "subject_type_id": "c2b3d4e5-0000-0000-0000-000000000000", "summary": "The treatment improved conversion", "tags": [ "growth" ], "teams": [ "growth" ], "updated_at": "2026-08-05T09:30:00Z" }, "id": "550e8400-e29b-41d4-a716-446655440000", "type": "experiments" } ] } ``` {% /tab %} {% /tab %} {% tab title="400" %} Invalid query parameter: bad page[offset]/page[limit], unknown sort field, invalid status, malformed protocol_id UUID, invalid result timestamp range, or a timestamp filter that is not RFC3339. {% tab title="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 title="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 %} {% /tab %} {% tab title="401" %} Missing or invalid authentication (dd-api-key + dd-application-key headers, or a valid user session). {% tab title="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 title="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 %} {% /tab %} {% tab title="403" %} Authenticated caller lacks the product_analytics_experiments_read permission. {% tab title="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 title="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 %} {% /tab %} {% tab title="429" %} Too many requests {% tab title="Model" %} API error response. | Field | Type | Description | | ------------------------ | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tab %} ### Code Example ##### \# Use a Personal Access Token or Service Access Token export DD_BEARER_TOKEN="" \# Curl command curl -X GET "https://api.datadoghq.com/api/v2/experiments" \ -H "Accept: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" {% /tab %}