> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# List macro suggestion insights

> See how each org-wide macro performs as a suggested macro over the last 30 days: times shown and used, hit rate, and its learning state.

## Reading the numbers

Counts cover the last 30 days (`window_days`):

* `shown` — times the macro was suggested to an agent.
* `applied` — times an agent used it from the suggestions.
* `missed` — times an agent reached for it through search instead.
* `hit_rate` — `applied` divided by `shown`, or `null` when it was never shown.
* `threshold` — how close a match the macro needs to be suggested right now.
* `weekly` — 12 weekly counts, oldest first, each with a `week_start` (the Monday, UTC). Empty unless you pass `include_weekly=true`.

Macros learn from how agents use them, and `state` says where each one stands:

| `state` | Meaning |
| - | - |
| `learning` | Not enough use yet to tell. |
| `steady` | Suggested at the usual bar. |
| `proven` | Agents use it, so it is suggested a little earlier (a lower `threshold`). |
| `muted` | Often suggested and never used, so it needs a closer match (a higher `threshold`). |
| `off` | The macro is excluded from suggestions, or suggested macros are off for the workspace. |

Personal macros are not included. Macros excluded from suggestions with no activity in the last 30 days are left out. To keep a macro out of suggestions, set `exclude_from_suggestions` with [Update a macro](./update).


## OpenAPI

````yaml get /macros/suggestion-insights
openapi: 3.1.0
info:
  title: OpenCX API
  description: >

    OpenCX is an AI-powered, all-in-one platform for customer support and
    outbound communications.


    Use this API to manage your OpenCX organization's AI agents, actions,
    conversations, contacts, and more.


    To get started, generate a new API key from the dashboard.


    ## Authentication

    All API endpoints require authentication using a Bearer token. You can
    generate an API key from your OpenCX dashboard.


    ## Rate Limiting

    API requests are rate limited to ensure fair usage. The current limits are:

    - 100 requests per minute for standard endpoints

    - 1000 requests per minute for streaming endpoints


    ## Error Handling

    The API uses standard HTTP status codes and returns detailed error messages
    in the response body.
  version: 1.0-beta
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: http://localhost:8080
    description: Development
  - url: https://api.open.cx
    description: Production
security:
  - bearerAuth: []
paths:
  /macros/suggestion-insights:
    get:
      summary: List macro suggestion insights
      description: >-
        How each org-wide macro is doing as a suggestion over the last 30 days:
        how often it was shown, used from the suggestions, or reached for by
        search instead, and the state it is in (`learning`, `steady`, `proven`,
        `muted`, or `off` when the macro is excluded or suggestions are off).
        Pass `include_weekly=true` for 12 weekly counts per macro. Macros
        excluded from suggestions with no activity in the last 30 days are left
        out.
      operationId: listMacroSuggestionInsights
      parameters:
        - schema:
            type: string
            enum:
              - 'true'
              - 'false'
          in: query
          name: include_weekly
          required: false
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MacroSuggestionInsightsListDto'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
components:
  schemas:
    MacroSuggestionInsightsListDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/MacroSuggestionInsightsListDto'
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/MacroSuggestionInsightsDto'
      required:
        - items
      additionalProperties: false
    ErrorDto:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string
    MacroSuggestionInsightsDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/MacroSuggestionInsightsDto'
      type: object
      properties:
        saved_reply_id:
          type: string
        window_days:
          type: number
          const: 30
        state:
          type: string
          enum:
            - 'off'
            - learning
            - proven
            - steady
            - muted
        shown:
          type: number
        applied:
          type: number
        missed:
          type: number
        hit_rate:
          anyOf:
            - type: number
            - type: 'null'
        threshold:
          type: number
        weekly:
          type: array
          items:
            type: object
            properties:
              week_start:
                type: string
              shown:
                type: number
              applied:
                type: number
              missed:
                type: number
            required:
              - week_start
              - shown
              - applied
              - missed
            additionalProperties: false
      required:
        - saved_reply_id
        - window_days
        - state
        - shown
        - applied
        - missed
        - hit_rate
        - threshold
        - weekly
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.