---
title: "List Macros"
method: GET
path: "/api/v2/macros"
tags: ["Macros"]
---

# List Macros

`GET /api/v2/macros`

Lists all shared and personal macros available to the current user. For admins, the API returns all macros for the account, including the personal macros of agents and other admins.

#### Pagination

- Cursor pagination (recommended)
- Offset pagination

See [Pagination](/api-reference/introduction/pagination/).

Returns a maximum of 100 records per page.

#### Allowed For
* Agents

## Query parameters

- `page[before]` string
- `page[after]` string
- `page[size]` integer
- `include` string
- `access` string
- `active` boolean
- `category` integer
- `group_id` integer
- `only_viewable` boolean
- `sort_by` string
- `sort_order` string

## Response `200`

Success Response

- MacrosResponse
  - `macros` MacroObject[]
    - `actions` ActionObject[], required — Each action describes what the macro will do. See [Actions reference](/documentation/ticketing/reference-guides/actions-reference)
      - `field` string — The name of a ticket field to modify
      - `value` string — The new value of the field
    - `active` boolean — Useful for determining if the macro should be displayed
    - `created_at` string, date-time — The time the macro was created
    - `default` boolean — If true, the macro is a default macro
    - `description` string, nullable — The description of the macro
    - `id` integer — The id automatically assigned when a macro is created
    - `position` integer — The position of the macro
    - `restriction` object, nullable — Access to this macro. A null value allows unrestricted access for all users in the account
    - `title` string, required — The title of the macro
    - `updated_at` string, date-time — The time of the last update of the macro
    - `url` string — A URL to access the macro's details
    - `app_installation` string, nullable — The app installation that requires each macro, if present
    - `categories` string, nullable — The macro categories
    - `permissions` string, nullable — Permissions for each macro
    - `usage_1h` integer — The number of times each macro has been used in the past hour
    - `usage_7d` integer — The number of times each macro has been used in the past week
    - `usage_24h` integer — The number of times each macro has been used in the past day
    - `usage_30d` integer — The number of times each macro has been used in the past thirty days
  - `count` integer — the total record count
  - `next_page` string, url, nullable — the URL of the next page
  - `previous_page` string, url, nullable — the URL of the previous page

## Changes

> 29 revisions in range; 1 not diffed, 1 could not be searched.

- **2025-06-12** `edbf399da815` — 3 info
  - added the new optional `query` request parameter `page[after]`
  - added the new optional `query` request parameter `page[before]`
  - added the new optional `query` request parameter `page[size]`

[Change history](https://skmtc.dev/botbrains-io/apis/support-api/changes/api/v2/macros/get.md)

---

[API](https://skmtc.dev/botbrains-io/apis/support-api.md) · [All operations](https://skmtc.dev/botbrains-io/apis/support-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/botbrains-io/support-api/revisions/d53eac07ba68/schema)