---
title: "List experiment protocols"
method: GET
path: "/api/v2/experiments/protocols"
tags: ["Experiments"]
---

# List experiment protocols

`GET /api/v2/experiments/protocols`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/experiments/protocols`
- 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: <https://skmtc.dev/datadog/apis/datadog-api-v2-collection/docs/api/v2/experiments/protocols/get.ts> (a function with typed inputs; its response is checked against the schema)

List draft, published, and archived experiment protocols. Omit filter[status] to return all statuses. Only published protocols can be used to create experiments.

## Query parameters

- `filter[status]` ExperimentsPublicProtocolResponseDataAttributesStatus[]
- `filter[primary_metric_id]` string, uuid: Filter by the UUID of the primary metric in the protocol template.
- `filter[query]` string: Find protocols whose names contain the search text, regardless of case. Leading and trailing spaces are ignored. Blank values apply no filter. The maximum length is 1024 UTF-8 bytes.
- `filter[subject_type_id]` string, uuid: Filter by the UUID of the subject type in the protocol template.
- `page[limit]` integer: Number of results per page. The default is 25. Values above 50 are reduced to 50.
- `page[offset]` integer: Number of results to skip before returning this page.
- `sort` string: Sort by `name`, `subject_type_name`, `primary_metric_name`, or `updated_at`. Prefix with `-` for descending order. The default is `-updated_at`.

## Response `200`

OK

- ExperimentsPublicProtocolListResponseArray: List of protocol resources with pagination information.
  - `data` ExperimentsPublicProtocolListResponseData[], required: Resources returned in this response.
    - `attributes` ExperimentsPublicProtocolListResponseDataAttributes: Summary of the protocol and its selected subject type and primary metric.
      - `description` string: Text that explains the protocol.
      - `experiment_count` integer, required: Number of experiments in the organization that use this protocol, excluding deleted experiments.
      - `name` string, required: Display name of the protocol.
      - `primary_metric` ExperimentsPublicProtocolResponseDataAttributesSubjectType: Subject type selected by the protocol.
        - `id` string: ID of the subject type.
        - `name` string: Display name of the subject type.
      - `primary_metric_id` string: ID of the primary metric supplied by the protocol.
      - `status` 'DRAFT' | 'PUBLISHED' | 'ARCHIVED', required: Publication status of the protocol.
      - `subject_type` ExperimentsPublicProtocolResponseDataAttributesSubjectType: Subject type selected by the protocol.
        - `id` string: ID of the subject type.
        - `name` string: Display name of the subject type.
      - `subject_type_id` string: ID of the subject type used by this configuration.
      - `updated_at` string, required: RFC3339 update time. Preserve all fractional seconds when passing this value as `expected_updated_at`.
    - `id` string, uuid, required: ID of the protocol.
    - `type` 'protocols', required: Protocols 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`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `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)