---
title: "List shadow experiments"
method: GET
path: "/v2/projects/{projectId}/endpoints/{endpointId}/shadowExperiments"
tags: ["ShadowExperimentService"]
---

# List shadow experiments

`GET /v2/projects/{projectId}/endpoints/{endpointId}/shadowExperiments`

## Request

- Base URL: `https://api.together.ai`
- URL: `https://api.together.ai/v2/projects/{projectId}/endpoints/{endpointId}/shadowExperiments`
- Auth: HTTP bearer

Lists experiments that mirror sampled endpoint traffic to target deployments without affecting client responses. Set `includeTargets=true` to include target details inline.

## Path parameters

- `projectId` string, required: Project identifier.
- `endpointId` string, required: Endpoint identifier.

## Query parameters

- `limit` integer: Maximum number of shadow experiments to return. Max 500, defaults to 50.
- `after` string: Cursor from a previous shadow experiment list response.
- `includeTargets` boolean: Whether to include target deployments in each returned shadow experiment.

## Response `200`

OK

- DEListShadowExperimentsResponse: Response containing shadow experiments and pagination metadata.
  - `data` DEShadowExperiment[], required: Shadow experiments under the endpoint.
    - `id` string, required: Output only. Unique shadow experiment identifier.
    - `projectId` string, required: Output only. Project that owns the parent endpoint.
    - `endpointId` string, required: Output only. Endpoint whose traffic this experiment samples.
    - `name` string, required: Human-readable shadow experiment name, unique within the endpoint. At most 256 characters.
    - `description` string: User defined description.
    - `source` DEShadowExperimentSourceResponse, required: Endpoint traffic source returned for a shadow experiment.
      - `endpoint` DEShadowExperimentEndpointSourceResponse, required: Endpoint-level source returned for a shadow experiment.
        - `sampling` union, required: Sampling strategy returned for endpoint-level shadow traffic.
          - object
            - `uniform` DEShadowExperimentUniformSamplingResponse, required: Fixed-rate random sampling returned by the API. A zero rate may be omitted by JSON serialization.
              - …
          - object
            - `keyBased` DEShadowExperimentKeyBasedSamplingResponse, required: Fixed-rate sticky-key sampling returned by the API. A zero rate may be omitted by JSON serialization.
              - …
          - object
            - `adaptiveUniform` DEShadowExperimentAdaptiveUniformSamplingResponse, required: Adaptive random sampling returned by the API.
              - …
          - object
            - `adaptiveKeyBased` DEShadowExperimentAdaptiveKeyBasedSamplingResponse, required: Adaptive sticky-key sampling returned by the API.
              - …
    - `targets` DEShadowExperimentTarget[], required: Target deployments that receive mirrored traffic.
      - `id` string, required: Output only. Unique shadow experiment target identifier.
      - `experimentId` string, required: Output only. Shadow experiment this target belongs to.
      - `name` string, required: Human-readable target name, unique within the shadow experiment. At most 256 characters.
      - `targetDeploymentId` string, required: Deployment under the parent endpoint that receives mirrored traffic. It must not be a live traffic-split member or the source or target of an active rollout; traffic-split weight 0 warm-up targets are allowed.
      - `description` string: Optional free-form target description.
      - `createdAt` string, date-time, required: Output only. Timestamp when the target was created.
      - `updatedAt` string, date-time, required: Output only. Timestamp when the target was last updated.
      - `etag` string, required: Opaque version tag for optimistic concurrency control. Returned on read; set it on update or delete requests for consistent read-modify-write.
    - `createdBy` string, required: Identifier of the principal that created the experiment.
    - `createdAt` string, date-time, required: Timestamp when the experiment was created.
    - `updatedAt` string, date-time, required: Timestamp when the experiment was last updated.
    - `etag` string, required: Opaque version tag for optimistic concurrency control. Returned on read; set it on update or delete requests for consistent read-modify-write.
    - `state` 'SHADOW_EXPERIMENT_STATE_ACTIVE' | 'SHADOW_EXPERIMENT_STATE_INACTIVE', required: Derived serving state, active when the experiment has at least one target.
  - `next_cursor` string: Cursor for the next page. Null if there are no more results.
  - `object` 'list', required: Object type. Always `list`.

## Other responses

- `400`: Invalid request
- `default`: Default error response

## Changes

- **2026-10-22** `bb5257b3173a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/together/apis/together-apis/changes/v2/projects/:projectId/endpoints/:endpointId/shadowExperiments/get.md)

---

[API](https://skmtc.dev/together/apis/together-apis.md) - [All operations](https://skmtc.dev/together/apis/together-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/together/apis/together-apis/revisions/93438ddac711?raw)