---
title: "Exclude a video from GMV Max"
method: POST
path: "/gmv-max/excluded-videos"
tags: ["GMV Max"]
---

# Exclude a video from GMV Max

`POST /gmv-max/excluded-videos`

## Request

- Base URL: `https://api.reacherapp.com/public/v1`
- URL: `https://api.reacherapp.com/public/v1/gmv-max/excluded-videos`
- Auth: API key in header `x-api-key` and API key in header `x-shop-id`

Exclude ONE video (creative) from this shop's GMV Max delivery, by TikTok `video_id`, without excluding its creator — use this to cut an unprofitable creative (e.g. zero orders at $10+ spend) while the creator's other videos keep delivering. The reconcile job removes the creative from every active campaign it is delivering in within ~4 hours and verifies it flipped to EXCLUDED. Idempotent on (shop, video_id): re-excluding an already excluded video keeps its current applied_status. Requires `read_write` scope and an `Idempotency-Key`. Single shop only. For many videos at once use POST /gmv-max/excluded-videos/bulk.

## Headers

- `Idempotency-Key` string, nullable

## Request body

- GmvMaxExcludeVideoRequest: POST /gmv-max/excluded-videos request body — exclude ONE video (creative) from the shop's GMV Max delivery without excluding its creator. Idempotent on (shop, video_id).
  - `video_id` string, required: The TikTok video id to exclude — the same `video_id` / `material_id` returned by the GMV Max video and creative-metrics tools (a pasted TikTok video URL is accepted and unwrapped). Only this creative comes off spend; the creator's other videos keep delivering.
  - `reason` string, nullable: Optional free-text note (e.g. 'zero orders at $12 spend').

## Response `200`

Successful Response

- GmvMaxExcludeVideoWriteResponse: POST /gmv-max/excluded-videos — echoes the excluded video row.
  - `data` GmvMaxExcludedVideoItem, required: One video (creative) excluded from the shop's GMV Max delivery.
    - `video_id` string, required: The TikTok video id (== creative material_id).
    - `source` string, required: How the exclusion was created: `manual` (API or portal), `auto_rule`, or `auto_ai` (the shop's AI-labelled video auto-exclude).
    - `reason` string, nullable: Free-text note stored with the exclusion.
    - `excluded_campaign_count` integer: How many campaigns the video is confirmed EXCLUDED from after the last reconcile.
    - `applied_status` string, required: Whether the exclusion has taken effect on spend: `applied` (live), `pending` (armed, reconcile job hasn't run yet or the video has no known product yet), `no_creatives` (the video is not in any active campaign right now), `attempted`, or `failed` (an actively delivering placement could not be excluded).
    - `decided_by` string, nullable: Who created the exclusion (`api_key:<prefix>` for public-API writes).
    - `created_at` string, nullable
    - `updated_at` string, nullable: When the reconcile job last touched this row.

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `409`: Conflict
- `422`: Unprocessable Entity
- `429`: Too Many Requests
- `500`: Internal Server Error

## Changes

> 76 revisions in range; 1 not diffed.

- **2026-09-19** `291230805105`: 2 breaking
  - the `data/created_at/anyOf[subschema #1]/` response's property format changed from `date-time` to no format for status `200`
  - the `data/updated_at/anyOf[subschema #1]/` response's property format changed from `date-time` to no format for status `200`
- **2026-09-12** `19eefbad93ec`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/reacherapp/apis/reacher-data-api/changes/gmv-max/excluded-videos/post.md)

---

[API](https://skmtc.dev/reacherapp/apis/reacher-data-api.md) - [All operations](https://skmtc.dev/reacherapp/apis/reacher-data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/reacherapp/apis/reacher-data-api/revisions/63ce74b30b5a?raw)