---
title: "Create an AI Gateway data capture override"
method: POST
path: "/api/v2/data-capture/overrides"
tags: ["AI Gateway"]
---

# Create an AI Gateway data capture override

`POST /api/v2/data-capture/overrides`

## Request

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

Create a scoped override with a client-generated UUID and the current `configuration_revision`. If the override can enable full capture for more traffic, set `confirm_full_capture` to `true`. Returns HTTP 409 when `configuration_revision` is stale, the UUID already exists, or the organization has 100 overrides. Missing `configuration_revision` or required full-capture confirmation returns HTTP 400. Retrying an accepted create with the same UUID returns HTTP 409. To undo a create, read the current configuration revision and delete the override using its returned override revision.

## Request body

- AiGatewayCaptureCreateRequest: Request body for creating a scoped data capture override.
  - `data` AiGatewayCaptureCreateRequestData, required: New data capture override with a client-generated UUID and its settings.
    - `attributes` AiGatewayCaptureCreateRequestDataAttributes, required: Settings and configuration revision for creating the override.
      - `configuration_revision` string, required: Opaque revision of the organization default and all overrides. Writes require the revision returned by a current read or preview.
      - `confirm_full_capture` boolean: Set to `true` to confirm a change that can enable full capture, including a deletion that causes a `full_capture` override or the organization default to apply.
      - `metadata_capture` AiGatewayMetadataCaptureItem[]: Items Metadata-only capture adds, each listed once. An item requires the items whose information it already reveals: `tool_output_size`, `tool_names` and `conversation_shape` require `tool_usage`, and `input_size_by_role` requires `tool_output_size`. A set that leaves out a required item is rejected. When several Metadata-only overrides match a request, it gets only the items all of them select.
      - `mode` 'metadata_only' | 'full_capture', required: Capture mode for matching traffic.
      - `name` string, required: Display name of the override. Names need not be unique; identify overrides by `id`.
      - `operation` 'create' | 'replace' | 'delete': Proposed operation for preview. Write endpoints infer it from the HTTP method.
      - `revision` integer: Current override revision, required for replacement or deletion.
      - `scope` AiGatewayCaptureScope, required: All selected filters combine with AND, with one value per filter. The `model` and `provider` tags apply to each actual direct or routed attempt, including fallback destinations. Routes are not selectable filters. At least one filter is required. If any matching override uses `metadata_only`, that mode applies. Otherwise, if any matching override uses `full_capture`, that mode applies. The organization default applies only when no override matches. Overrides have no priority or specificity ordering.
        - `tags` object: Exact-match request tags with lowercase keys. The reserved `model` tag is the canonical model ID, and the reserved `provider` tag is the configured connection slug. The server sets both. Custom tags come from `x-dd-tag` headers. Keys and values must not have leading or trailing white space. Values are case-sensitive.
        - `team_id` string, uuid: UUID of a Datadog team. Matches the authorized team selected by the `x-ai-gateway-team` request header. Requests without this header do not match team-scoped overrides. Open-membership teams cannot scope overrides.
        - `user_id` string, uuid: Authenticated Datadog user UUID in this organization.
    - `id` string, uuid, required: Client-generated UUID for the override.
    - `type` 'data-capture-overrides', required: Data capture overrides resource type.

## Response `201`

Created

- AiGatewayCaptureOverrideResponse: Response containing a data capture override after creation or replacement.
  - `data` AiGatewayCaptureOverrideResponseData, required: Saved data capture override with its identifier, mode, scope, and revision.
    - `attributes` AiGatewayCaptureOverrideResponseDataAttributes, required: Saved name, capture mode, request filters, and revision of the override.
      - `metadata_capture` AiGatewayMetadataCaptureItem[]: Items Metadata-only capture adds, each listed once. An item requires the items whose information it already reveals: `tool_output_size`, `tool_names` and `conversation_shape` require `tool_usage`, and `input_size_by_role` requires `tool_output_size`. A set that leaves out a required item is rejected. When several Metadata-only overrides match a request, it gets only the items all of them select.
      - `mode` 'metadata_only' | 'full_capture', required: Capture mode for matching traffic.
      - `name` string, required: Display name of the override. Names need not be unique; identify overrides by `id`.
      - `revision` integer, required: Current override revision, required for replacement or deletion.
      - `scope` AiGatewayCaptureResponseScope, required: Visible request filters. Provider and model tags are withheld when the caller cannot view them. An empty object or empty tags can represent a fully restricted scope; scope_restricted identifies redaction.
        - `tags` object: Exact-match request tags with lowercase keys. The reserved `model` tag is the canonical model ID, and the reserved `provider` tag is the configured connection slug. The server sets both. Custom tags come from `x-dd-tag` headers. Keys and values must not have leading or trailing white space. Values are case-sensitive.
        - `team_id` string, uuid: UUID of a Datadog team. Matches the authorized team selected by the `x-ai-gateway-team` request header. Requests without this header do not match team-scoped overrides. Open-membership teams cannot scope overrides.
        - `user_id` string, uuid: Authenticated Datadog user UUID in this organization.
      - `scope_restricted` boolean, required: Whether provider or model scope metadata was withheld. Omit unchanged scope on replacement to preserve it.
    - `id` string, uuid, required: UUID of the saved override, used to retrieve it from the configuration or change it.
    - `type` 'data-capture-overrides', required: Data capture overrides resource type.

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `409`: Conflict
- `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)