Browse the docs

List velocity controls

GET /v1/api-gateway/controls/velocity

Paginated list of the organization's velocity controls. per_page is capped at 100. Pass include_deleted=true to include deleted controls (they are returned unmarked).

Request

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

Query parameters

Field	Type	Description
`page`	integer	1-based page number. Defaults to 1.
`current_page`	integer	Page number, starting at `1` — the canonical spelling, accepted on every paginated endpoint and matching `pagination.current_page` in the response. `page` means the same thing and keeps working; if both are sent, `current_page` wins.
`per_page`	integer	Page size. Defaults to 10. A value above `100` is not rejected: it is silently reduced to `100`, and `pagination.per_page` in the response reports the size actually applied — read it back rather than assuming the value you sent.
`card_id`	string, uuid	Return only controls attached to this card.
`include_deleted`	boolean	Set to `true` to include deleted controls. Deleted controls are excluded by default.

Example request

cURL

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

Responses

200 Success

Field	Type	Description
`velocityControls` required	array of object
`velocityControls[].id` required	string	Velocity control id.
`velocityControls[].card_id` required	string, nullable	Card this control applies to, or null for cardholder-level controls.
`velocityControls[].cardholder_id` required	string, nullable	Cardholder this control applies to, or null for card-level controls.
`velocityControls[].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.
`velocityControls[].type` required	string	Control type: `SPEND` or `COUNT`.
`velocityControls[].velocity_window` required	string	Window the limit applies to: `MONTH`, `DAY`, `WEEK` or `TOTAL`, all UTC.
`velocityControls[].mode` required	string	`STRICT` declines a breach; `WATCH` only reports it over the webhook.
`velocityControls[].only_merchants` required	array of object	Merchant allowlist, or null when the card is not locked to any merchant.
`velocityControls[].only_merchants[].name`	string
`velocityControls[].only_merchants[].mcc`	string
`velocityControls[].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`
`velocityControls[].enabled` required	integer	1 when enabled, otherwise 0.One of: `0`, `1`
`velocityControls[].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.
`velocityControls[].created_at` required	string
`velocityControls[].updated_at` required	string
`pagination` required	object
`pagination.total` required	integer	Total number of items across all pages.
`pagination.last_page` required	integer	Number of the last page (0 when there are no items).
`pagination.prev_page` required	integer, nullable	Previous page number, or null on the first page.
`pagination.next_page` required	integer, nullable	Next page number, or null on the last page.
`pagination.per_page` required	integer	Page size that was applied.
`pagination.current_page` required	integer	1-based current page.
`pagination.from` required	integer	1-based index of the first item on this page (0 when empty).
`pagination.to` required	integer	1-based index of the last item on this page (0 when empty).

JSON

{
  "velocityControls": [
    {
      "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"
    }
  ],
  "pagination": {
    "total": 1,
    "last_page": 1,
    "prev_page": null,
    "next_page": null,
    "per_page": 10,
    "current_page": 1,
    "from": 1,
    "to": 1
  }
}

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

The card_id filter does not match a card in this organization.

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 16, 2026