---
title: "Create a shadow experiment"
method: POST
path: "/projects/{projectId}/endpoints/{endpointId}/shadowExperiments"
tags: ["ShadowExperimentService"]
---

# Create a shadow experiment

`POST /projects/{projectId}/endpoints/{endpointId}/shadowExperiments`

Creates an experiment that mirrors a sampled portion of endpoint traffic to one or more target deployments without returning their responses to clients. Add a description with the update operation after creation.

## Path parameters

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

## Request body

- DECreateShadowExperimentRequest — Sampling strategy and optional initial targets for mirroring endpoint requests without affecting client responses.
  - `name` string, required — Human-readable shadow experiment name, unique within the endpoint. At most 256 characters.
  - `source` DEShadowExperimentSource, required — Traffic source for a shadow experiment. The public API supports endpoint sources only.
    - `endpoint` DEShadowExperimentEndpointSource, required — Endpoint-level source that samples endpoint traffic at the API gateway.
      - `sampling` union, required — Sampling strategy for endpoint-level shadow traffic. Exactly one strategy must be set.
        - object
          - `uniform` DEShadowExperimentUniformSampling, required — Fixed-rate random sampling of endpoint requests.
            - `rate` number, required — Required fraction of requests to sample, from 0.0 to 1.0.
        - object
          - `keyBased` DEShadowExperimentKeyBasedSampling, required — Fixed-rate sampling of distinct key values with sticky decisions.
            - `rate` number, required — Required fraction of distinct key values to sample, from 0.0 to 1.0.
            - `key` string, required — Required request-body field used as the sticky sampling key.
        - object
          - `adaptiveUniform` DEShadowExperimentAdaptiveUniformSampling, required — Adaptive random sampling that throttles toward a target QPS.
            - `targetQps` number, required — Required per-gateway-replica target QPS for adaptive sampling.
            - `window` string — Optional sliding window for QPS observation. Defaults to 60s and must not be negative.
        - object
          - `adaptiveKeyBased` DEShadowExperimentAdaptiveKeyBasedSampling, required — Adaptive sticky-key sampling that throttles toward a target QPS.
            - `targetQps` number, required — Required per-gateway-replica target QPS for adaptive sampling.
            - `key` string, required — Required request-body field used as the sticky sampling key.
            - `window` string — Optional sliding window for QPS observation. Defaults to 60s and must not be negative.
  - `targets` DECreateShadowExperimentTargetRequest[] — Optional initial target deployments. At most 100 targets; manage later changes through the target APIs.
    - `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.

## Response `200`

OK

- DEShadowExperiment — Experiment that mirrors sampled endpoint requests to target deployments without changing client responses.
  - `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.
            - `rate` number — Fraction of requests sampled, from 0.0 to 1.0.
        - object
          - `keyBased` DEShadowExperimentKeyBasedSamplingResponse, required — Fixed-rate sticky-key sampling returned by the API. A zero rate may be omitted by JSON serialization.
            - `rate` number — Fraction of distinct key values sampled, from 0.0 to 1.0.
            - `key` string, required — Request-body field used as the sticky sampling key.
        - object
          - `adaptiveUniform` DEShadowExperimentAdaptiveUniformSamplingResponse, required — Adaptive random sampling returned by the API.
            - `targetQps` number, required — Per-gateway-replica target QPS.
            - `window` string — Sliding window for QPS observation when explicitly configured.
        - object
          - `adaptiveKeyBased` DEShadowExperimentAdaptiveKeyBasedSamplingResponse, required — Adaptive sticky-key sampling returned by the API.
            - `targetQps` number, required — Per-gateway-replica target QPS.
            - `key` string, required — Request-body field used as the sticky sampling key.
            - `window` string — Sliding window for QPS observation when explicitly configured.
  - `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.

## Other responses

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

---

[API](https://skmtc.net/together/apis/together-apis.md) · [All operations](https://skmtc.net/together/apis/together-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/together/together-apis/versions/f26a23fab8e0/schema)