{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/gtm-api/main/json-schema/gtm-api-get-api-request-metrics-request-schema.json",
  "title": "GetApiRequestMetricsRequest",
  "description": "Request body of `get_api_request_metrics`.",
  "x-generated": "2026-10-18",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/gtm-api-id-openapi.yaml#/components/schemas/GetApiRequestMetricsRequest",
  "type": "object",
  "properties": {
    "filter": {
      "type": "object",
      "properties": {
        "sid": {
          "type": "object",
          "properties": {
            "eq": {
              "type": "string"
            },
            "in": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "additionalProperties": false
        },
        "service": {
          "type": "object",
          "properties": {
            "eq": {
              "type": "string",
              "enum": [
                "id",
                "linkedin",
                "orchestration"
              ]
            },
            "ne": {
              "type": "string",
              "enum": [
                "id",
                "linkedin",
                "orchestration"
              ]
            },
            "in": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "id",
                  "linkedin",
                  "orchestration"
                ]
              }
            },
            "nin": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "id",
                  "linkedin",
                  "orchestration"
                ]
              }
            }
          },
          "additionalProperties": false,
          "description": "Which answering service: id (keys, teams, billing), linkedin (the channel), orchestration (mass actions, webhooks). Excluded services are not asked."
        },
        "surface": {
          "type": "object",
          "properties": {
            "eq": {
              "type": "string",
              "enum": [
                "api_key",
                "agent",
                "oauth_other"
              ]
            },
            "ne": {
              "type": "string",
              "enum": [
                "api_key",
                "agent",
                "oauth_other"
              ]
            },
            "in": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "api_key",
                  "agent",
                  "oauth_other"
                ]
              }
            },
            "nin": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "api_key",
                  "agent",
                  "oauth_other"
                ]
              }
            }
          },
          "additionalProperties": false,
          "description": "api_key = bearer keys (scripts, n8n); agent = OAuth clients of kind agent (Claude, Cursor); oauth_other = other OAuth clients."
        },
        "credential_kind": {
          "type": "object",
          "properties": {
            "eq": {
              "type": "string",
              "enum": [
                "api_key",
                "oauth"
              ]
            },
            "ne": {
              "type": "string",
              "enum": [
                "api_key",
                "oauth"
              ]
            },
            "in": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "api_key",
                  "oauth"
                ]
              }
            },
            "nin": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "api_key",
                  "oauth"
                ]
              }
            }
          },
          "additionalProperties": false
        },
        "client_sid": {
          "type": "object",
          "properties": {
            "eq": {
              "type": "string"
            },
            "ne": {
              "type": "string"
            },
            "in": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "nin": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "additionalProperties": false,
          "description": "The credential: an api key sid (id_ak_*) or an OAuth client sid (id_oc_*). \"What did Claude do\" = that client's sid."
        },
        "actor_sid": {
          "type": "object",
          "properties": {
            "eq": {
              "type": "string"
            },
            "in": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "is_null": {
              "type": "boolean"
            }
          },
          "additionalProperties": false,
          "description": "The member an OAuth client delegates for (us_mb_*); is_null:true = api-key traffic."
        },
        "entity": {
          "type": "object",
          "properties": {
            "eq": {
              "type": "string"
            },
            "ne": {
              "type": "string"
            },
            "in": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "nin": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "additionalProperties": false,
          "description": "The entity the route names, snake singular: linkedin_conversation, linkedin_message, mass_action, api_key."
        },
        "operation": {
          "type": "object",
          "properties": {
            "eq": {
              "type": "string",
              "enum": [
                "get",
                "search",
                "metrics",
                "group_by",
                "create",
                "update",
                "delete",
                "action"
              ]
            },
            "ne": {
              "type": "string",
              "enum": [
                "get",
                "search",
                "metrics",
                "group_by",
                "create",
                "update",
                "delete",
                "action"
              ]
            },
            "in": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "get",
                  "search",
                  "metrics",
                  "group_by",
                  "create",
                  "update",
                  "delete",
                  "action"
                ]
              }
            },
            "nin": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "get",
                  "search",
                  "metrics",
                  "group_by",
                  "create",
                  "update",
                  "delete",
                  "action"
                ]
              }
            }
          },
          "additionalProperties": false
        },
        "action_name": {
          "type": "object",
          "properties": {
            "eq": {
              "type": "string"
            },
            "in": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "is_null": {
              "type": "boolean"
            }
          },
          "additionalProperties": false,
          "description": "The verb of an action route (send, run_now); is_null:true = the six canonical operations."
        },
        "route": {
          "type": "object",
          "properties": {
            "eq": {
              "type": "string"
            },
            "ne": {
              "type": "string"
            },
            "in": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "nin": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "additionalProperties": false,
          "description": "The route key, exact: \"POST api/linkedin-conversations/search\"."
        },
        "account_sid": {
          "type": "object",
          "properties": {
            "eq": {
              "type": "string"
            },
            "ne": {
              "type": "string"
            },
            "in": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "nin": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "is_null": {
              "type": "boolean"
            }
          },
          "additionalProperties": false,
          "description": "The account the request named (ln_ac_*, em_ac_*): \"everything that was refused on this sender\". is_null:true = calls that named no account."
        },
        "status": {
          "type": "object",
          "properties": {
            "eq": {
              "type": "integer"
            },
            "ne": {
              "type": "integer"
            },
            "in": {
              "type": "array",
              "items": {
                "type": "integer"
              }
            },
            "nin": {
              "type": "array",
              "items": {
                "type": "integer"
              }
            },
            "gte": {
              "type": "integer"
            },
            "lte": {
              "type": "integer"
            },
            "gt": {
              "type": "integer"
            },
            "lt": {
              "type": "integer"
            }
          },
          "additionalProperties": false
        },
        "status_family": {
          "type": "object",
          "properties": {
            "eq": {
              "type": "string",
              "enum": [
                "2xx",
                "3xx",
                "4xx",
                "5xx"
              ]
            },
            "ne": {
              "type": "string",
              "enum": [
                "2xx",
                "3xx",
                "4xx",
                "5xx"
              ]
            },
            "in": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "2xx",
                  "3xx",
                  "4xx",
                  "5xx"
                ]
              }
            },
            "nin": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "2xx",
                  "3xx",
                  "4xx",
                  "5xx"
                ]
              }
            }
          },
          "additionalProperties": false,
          "description": "4xx and 5xx together are the errors every dashboard number counts."
        },
        "error_code": {
          "type": "object",
          "properties": {
            "eq": {
              "type": "string"
            },
            "ne": {
              "type": "string"
            },
            "in": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "nin": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "is_null": {
              "type": "boolean"
            }
          },
          "additionalProperties": false,
          "description": "The typed error code of the envelope that was returned (rate_limited, validation_failed, not_found); is_null:true = the calls that succeeded."
        },
        "error_reason": {
          "type": "object",
          "properties": {
            "eq": {
              "type": "string"
            },
            "ne": {
              "type": "string"
            },
            "in": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "nin": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "is_null": {
              "type": "boolean"
            }
          },
          "additionalProperties": false,
          "description": "The sub-code inside error.context (bucket_saturated, account_rate_exceeded, not_connected): what a status alone cannot say."
        },
        "error_cause": {
          "type": "object",
          "properties": {
            "eq": {
              "type": "string"
            },
            "ne": {
              "type": "string"
            },
            "in": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "nin": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "is_null": {
              "type": "boolean"
            }
          },
          "additionalProperties": false,
          "description": "The specific trigger a layered gate adds (held, daily_saturation, delay_not_elapsed, linkedin_quota_hit): held means a person paused the account, daily_saturation means the limit is spent, and a 429 does not tell them apart."
        },
        "occurred_at": {
          "type": "object",
          "properties": {
            "eq": {
              "type": "string"
            },
            "gte": {
              "type": "string"
            },
            "lte": {
              "type": "string"
            },
            "gt": {
              "type": "string"
            },
            "lt": {
              "type": "string"
            }
          },
          "additionalProperties": false,
          "description": "ISO 8601 UTC. The only time axis on search; ignored on metrics, where period is the window."
        },
        "trace_id": {
          "type": "object",
          "properties": {
            "eq": {
              "type": "string"
            },
            "in": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "is_null": {
              "type": "boolean"
            }
          },
          "additionalProperties": false,
          "description": "All the calls of one MCP turn share a trace id."
        }
      }
    },
    "period": {
      "type": "object",
      "properties": {
        "from": {
          "type": "string",
          "description": "ISO 8601 UTC window start (inclusive)."
        },
        "to": {
          "type": "string",
          "description": "ISO 8601 UTC window end (exclusive); at most 92 days after from."
        }
      },
      "required": [
        "from",
        "to"
      ],
      "description": "Required metrics window [from, to). Operators on occurred_at inside filter are ignored."
    },
    "group_by": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "service",
        "surface",
        "credential_kind",
        "client_sid",
        "entity",
        "operation",
        "route",
        "status_family",
        "occurred_day",
        "occurred_hour"
      ],
      "description": "Split the aggregate per key: client_sid / route / entity / status_family / service / surface = breakdowns (occurred_hour / occurred_day = a legacy time split; prefer bucket). Cap 500 groups."
    },
    "bucket": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "hour",
        "day"
      ],
      "description": "The time axis, independent of group_by: hour or day (UTC). Answers series.points[], one per bucket over the whole window, zeros filled, each with its own counts and group_by split."
    }
  },
  "required": [
    "period"
  ]
}