--- title: "List experiments" method: GET path: "/api/v2/experiments" tags: ["Experiments"] --- # List experiments `GET /api/v2/experiments` ## Request - Base URL: `https://api.datadoghq.com` - URL: `https://api.datadoghq.com/api/v2/experiments` - Auth: one of: - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY` - OAuth 2 - Authorization code: `/oauth2/v1/authorize` - Token URL: `/oauth2/v1/token` scopes: `product_analytics_experiments_read` - TypeScript: (a function with typed inputs; its response is checked against the schema) 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. ## Query parameters - `concluded_since` string, date-time: Return only experiments concluded at or after this RFC3339 timestamp. Inclusive, and excludes experiments that have not concluded. - `created_since` string, date-time: 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` string[]: Filter by protocol UUID. Repeat this parameter to supply several IDs. An experiment matches if it uses any listed protocol. - `results_updated_before` string, date-time: 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, date-time: 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` string[]: 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` string[]: Filter by tag name. Repeat this parameter to supply several tags. An experiment matches if it has at least one listed tag. ## Response `200` OK - ExperimentsExperimentV2ListDTOArray: Response containing a page of experiment summaries. - `data` ExperimentsExperimentV2ListDTOData[], required: Experiment summaries in the current page. - `attributes` ExperimentsExperimentV2ListDTODataAttributes: Summary fields for an experiment returned in a list. - `assignments_end_date` string, date-time, nullable: End of the window used to read experiment assignments. - `assignments_start_date` string, date-time, nullable: Start of the window used to read experiment assignments. - `concluded_at` string, date-time, nullable: Time when the experiment was concluded. - `conclusion` ExperimentsPatchExperimentV2ResponseDataAttributesConclusion: Outcome and supporting text recorded when the experiment is concluded. - `decision_reason` string, nullable: Reason for the recorded decision. - `outcome` 'POSITIVE' | 'NEGATIVE' | 'NEUTRAL' | 'INCONCLUSIVE' | 'MISCONFIGURED' | 'UNKNOWN', nullable: Recorded experiment outcome. - `summary` string, nullable: Summary of the experiment conclusion. - `created_at` string, date-time: Time when the experiment was created. - `events_end_date` string, date-time, nullable: End of the window used to read metric events. - `events_start_date` string, date-time, nullable: Start of the window used to read metric events. - `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. - `hypothesis` string: Expected effect that the experiment is designed to test. - `migration_metadata` unknown - `name` string: Display name of the experiment. - `pipeline_table_suffix` string: Suffix used for the experiment tables in the analysis pipeline. - `protocol_id` string: Identifier of the protocol associated with the experiment. - `related_links` ExperimentsCreateExperimentV2RequestDataAttributesRelatedLinksItems[]: External links associated with the experiment. - `id` string, nullable: Link ID. Omit it when adding a link. - `title` string, nullable: Optional display title. - `url` string, required: Absolute URL. - `results_last_updated` string, date-time, nullable: Time when the experiment results were last updated. - `status` 'DRAFT' | 'SCHEDULED' | 'IN_PROGRESS' | 'READY_FOR_DECISION' | 'DECISION_MADE' | 'CANCELLED' | 'UNKNOWN': Current stage in the experiment lifecycle. - `structured_metadata` ExperimentsStructuredMetadataResponse[]: Custom metadata fields and their values for the experiment. - `enum_values` string[]: Selected values for an enumerated metadata field. - `field_display_name` string: Display name of the metadata field. - `field_key` string, required: Key that identifies the metadata field. - `field_type` 'FREETEXT' | 'ENUM': Type of value stored in the structured metadata field. - `freetext_value` string: Text value for a free-text metadata field. - `subject_type_id` string, nullable: Identifier of the subject type used for experiment assignments. - `summary` string: Free-form summary of the experiment. - `tags` string[]: Tag names associated with the experiment. - `teams` string[]: Team handles associated with the experiment. - `updated_at` string, date-time: Time when the experiment was last updated. - `id` string, uuid, required: Identifier of the experiment. - `type` 'experiments', required: Experiments resource type. - `links` ExperimentsOffsetLinks: Links for navigating a paginated result set. - `first` string: URL of the first page of results. - `last` string: URL of the last page of results. - `next` string: URL of the next page of results. - `prev` string: URL of the previous page of results. - `self` string: URL of the current page of results. - `meta` ExperimentsOffsetMeta: Pagination information for a list response. - `page` ExperimentsOffsetMetaPage: Result counts and offsets for a page of results. - `first_offset` integer: Offset of the first page of results. - `last_offset` integer, nullable: Offset of the last page of results. - `limit` integer: Maximum number of results returned in one page. - `next_offset` integer, nullable: Offset of the next page of results. - `offset` integer: Number of results skipped before this page. - `prev_offset` integer, nullable: Offset of the previous page of results. - `total` integer, nullable: Total number of matching results across all pages. - `type` string: Pagination method used for this result set. ## Other responses - `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. - `401`: Missing or invalid authentication (dd-api-key + dd-application-key headers, or a valid user session). - `403`: Authenticated caller lacks the product_analytics_experiments_read permission. - `429`: Too many requests --- [API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/3f70db624329?raw)