Browse the docs

Get velocity control

GET /v2/api-gateway/controls/velocity/{id}

Pass include_deleted=true to read a deleted control; the response does not include a deletion timestamp.

Request

Authentication: your API key in the x-api-key header.

Path parameters

Field	Type	Description
`id` required	string	Velocity control id (`id` from `GET /controls/velocity`).

Query parameters

Field	Type	Description
`include_deleted`	boolean	Return the control even if it was deleted (`true`/`false`). Otherwise a deleted control is a 404.

Example request

cURL

curl --request GET \
     --url 'https://api.themooncard.com/v2/api-gateway/controls/velocity/{id}' \
     --header 'x-api-key: YOUR_API_KEY'

Responses

200 Success

Field	Type	Description
`id` required	string	Velocity control id.
`card_id` required	string, nullable	Card this control applies to, or null for cardholder-level controls.
`cardholder_id` required	string, nullable	Cardholder this control applies to, or null for card-level controls.
`limit_amount` required	number	The cap for the window: an amount in the card's own currency on a `SPEND` control, a whole number of approved authorizations on a `COUNT` one.
`type` required	string	Control type: `SPEND` or `COUNT`.
`velocity_window` required	string	Window the limit applies to: `MONTH`, `DAY`, `WEEK` or `TOTAL`, all UTC.
`mode` required	string	`STRICT` declines a breach; `WATCH` only reports it over the webhook.
`only_merchants` required	array of object	Merchant allowlist, or null when the card is not locked to any merchant.
`only_merchants[].name`	string
`only_merchants[].mcc`	string
`fixed` required	integer	1 when Moon fixed this control to the card it belongs to: the control that makes a card single-use, or the one that locks it to a merchant. A fixed control is read like any other but cannot be updated or deleted here (`CONTROL_IS_FIXED`). What to do instead depends on which one it is: a merchant lock is changed or removed through the card merchant-lock endpoints, while a single-use limit cannot be lifted at all — it ends with the card, so terminate the card to stop it being used. Otherwise 0.One of: `0`, `1`
`enabled` required	integer	1 when enabled, otherwise 0.One of: `0`, `1`
`metadata` required	object	The key-value data you stored on this velocity control, returned exactly as you sent it. An empty object when you never set any — it is never null.
`created_at` required	string
`updated_at` required	string

JSON

{
  "id": "e2c4a6b8-0d1f-4a2b-8c3d-4e5f6a7b8c9d",
  "card_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "cardholder_id": null,
  "limit_amount": 500,
  "type": "SPEND",
  "velocity_window": "MONTH",
  "mode": "STRICT",
  "only_merchants": null,
  "fixed": 0,
  "enabled": 1,
  "metadata": {
    "team": "field-ops"
  },
  "created_at": "2026-08-01T09:12:44.000Z",
  "updated_at": "2026-08-16T17:51:01.000Z"
}

400 Error

Validation failed (errors[] lists each offending field) or a domain rule rejected the request ({ message, code }).

The body is the standard error object: see Errors.

401 Error

Missing or invalid credentials, e.g. { "message": "Invalid API Key", "code": "UNAUTHORIZED" }.

The body is the standard error object: see Errors.

404 Error

Velocity control not found, deleted (without include_deleted), or not owned by this organization (VELOCITY_CONTROL_NOT_FOUND).

The body is the standard error object: see Errors.

500 Error

Unexpected server error. Body is { message: "Internal server error", code: "INTERNAL_SERVER_ERROR" }.

The body is the standard error object: see Errors.

Last updated August 24, 2026