> ## Documentation Index > Fetch the complete documentation index at: https://docs.gtm-api.com/llms.txt > Use this file to discover all available pages before exploring further. # API request metrics > Period-bound totals of the team's external API requests, merged across the answering services: total_count, error_count and the 2xx/3xx/4xx/5xx split in aggregated.counts; error_rate, avg_duration_ms, first/last_occurred_at in aggregated.metrics. Requires period {from, to} (ISO 8601 UTC, half-open, at most 92 days). Optional group_by splits the same numbers per key: client_sid ("how much does each agent call"), route or entity ("which tools"), status_family, service, surface (occurred_hour / occurred_day exist too but bucket is the better time axis). Optional bucket (hour | day) cuts the window into consecutive UTC buckets, series.points[] one per bucket over the whole window with zeros filled, each carrying its own counts and its own group_by split: "requests per day by type" is group_by entity + bucket day in one call. Use to answer "how many calls this week and how many failed" in one round-trip instead of paging the log. aggregated.counts.sources says which services answered. Contract: - MCP tool `get_api_request_metrics`, registry package `mcp.id/api_requests`, mount `id.platform`. - Operation `metrics`, response envelope `metrics`. - Flags: read only. ## OpenAPI ````yaml /api-reference/id/openapi.yaml post /api/api-requests/metrics openapi: 3.0.3 info: title: 'GTM API public contract: gtm.service.id' description: >- Identity, access and money: users, teams and members, API keys, OAuth clients and authorizations, billing products, subscriptions, transactions and payment methods, notifications, TLS certificates and support requests. GENERATED. This document is projected from the Zod MCP tool registry in `product/mcp/gtm.mcp` (one tool per public endpoint, 1:1). Do not edit it by hand; edit the tool definition and regenerate with `pnpm openapi:public`. Surface: the public `/api` contract of `gtm.service.id`, 75 operations. This is the only OpenAPI document the platform publishes. Internal (`/internal`) and health endpoints are deliberately absent: they are not part of any contract, they can change without notice, and the service source is their only description. Conventions: - Auth is a bearer JWT, optionally narrowed by the `Team-SID` header. - Every success body is an MCP envelope: `success: true` plus one typed `operation` shape (`search`, `get`, `create`, `update`, `delete`, `metrics`, `group_by`, `action`), and a `meta` block with `trace_id` for support. - Every failure is the same `McpError` envelope with a code from a fixed 16-code taxonomy, so a client maps errors once. - Lists page with `page_size` (0 to 500, default 50) plus an opaque forward `cursor`; `page_size: 0` returns counts only. - On `GET` and `DELETE`, object-valued query parameters (`filter`, `sort`) travel as JSON text and array-valued ones repeat as `name[]=value`. - The MCP-only `_meta` field (usage analytics) never reaches the backend and is not part of this contract. version: '1.0' contact: name: GTM API url: https://gtm-api.com email: support@gtm-api.com license: name: Proprietary url: https://gtm-api.com/license servers: - url: https://app.gtm-api.com/id/v4 description: Production, through the app.gtm-api.com gateway security: - BearerJwt: [] TeamSid: [] tags: - name: account_shares description: Registry package `mcp.id/account_shares`, served on MCP mount `id.access`. - name: api_keys description: Registry package `mcp.id/api_keys`, served on MCP mount `id.access`. - name: api_requests description: Registry package `mcp.id/api_requests`, served on MCP mount `id.platform`. - name: billing_payment_methods description: >- Registry package `mcp.id/billing_payment_methods`, served on MCP mount `id.billing`. - name: billing_products description: >- Registry package `mcp.id/billing_products`, served on MCP mount `id.billing`. - name: billing_subscriptions description: >- Registry package `mcp.id/billing_subscriptions`, served on MCP mount `id.billing`. - name: billing_transactions description: >- Registry package `mcp.id/billing_transactions`, served on MCP mount `id.billing`. - name: media_uploads description: >- Registry package `mcp.id/media_uploads`, served on MCP mount `id.platform`. - name: notifications description: >- Registry package `mcp.id/notifications`, served on MCP mount `id.platform`. - name: oauth_authorizations description: >- Registry package `mcp.id/oauth_authorizations`, served on MCP mount `id.access`. - name: oauth_clients description: Registry package `mcp.id/oauth_clients`, served on MCP mount `id.access`. - name: sessions description: Registry package `mcp.id/sessions`, served on MCP mount `id.identity`. - name: ssl_certificates description: >- Registry package `mcp.id/ssl_certificates`, served on MCP mount `id.platform`. - name: support_requests description: >- Registry package `mcp.id/support_requests`, served on MCP mount `id.platform`. - name: team_members description: Registry package `mcp.id/team_members`, served on MCP mount `id.identity`. - name: teams description: Registry package `mcp.id/teams`, served on MCP mount `id.identity`. - name: users description: Registry package `mcp.id/users`, served on MCP mount `id.identity`. paths: /api/api-requests/metrics: post: tags: - api_requests summary: API request metrics description: >- Period-bound totals of the team's external API requests, merged across the answering services: total_count, error_count and the 2xx/3xx/4xx/5xx split in aggregated.counts; error_rate, avg_duration_ms, first/last_occurred_at in aggregated.metrics. Requires period {from, to} (ISO 8601 UTC, half-open, at most 92 days). Optional group_by splits the same numbers per key: client_sid ("how much does each agent call"), route or entity ("which tools"), status_family, service, surface (occurred_hour / occurred_day exist too but bucket is the better time axis). Optional bucket (hour | day) cuts the window into consecutive UTC buckets, series.points[] one per bucket over the whole window with zeros filled, each carrying its own counts and its own group_by split: "requests per day by type" is group_by entity + bucket day in one call. Use to answer "how many calls this week and how many failed" in one round-trip instead of paging the log. aggregated.counts.sources says which services answered. Contract: - MCP tool `get_api_request_metrics`, registry package `mcp.id/api_requests`, mount `id.platform`. - Operation `metrics`, response envelope `metrics`. - Flags: read only. operationId: get_api_request_metrics requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GetApiRequestMetricsRequest' responses: '200': description: '`metrics` success envelope.' content: application/json: schema: $ref: '#/components/schemas/GetApiRequestMetricsResponse' 4XX: $ref: '#/components/responses/McpClientError' 5XX: $ref: '#/components/responses/McpServerError' components: schemas: GetApiRequestMetricsRequest: type: object description: Request body of `get_api_request_metrics`. 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".' 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. 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 nullable: true 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 nullable: true 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 GetApiRequestMetricsResponse: type: object properties: success: type: boolean enum: - true operation: type: string enum: - metrics metrics: type: object properties: period: type: object properties: from: type: string to: type: string required: - from - to aggregated: type: object properties: counts: type: object additionalProperties: {} metrics: type: object properties: error_rate: type: number nullable: true description: >- (4xx + 5xx) / total over the merged sources, 0..1; null when total is 0. avg_duration_ms: type: integer nullable: true description: >- Mean wall time of the rows that carry a duration; null when none. first_occurred_at: type: string nullable: true description: Earliest request in the window, ISO 8601 UTC. last_occurred_at: type: string nullable: true description: >- Latest request in the window: "when did my agent last call". required: - error_rate - avg_duration_ms - first_occurred_at - last_occurred_at groups: type: array items: type: object properties: key: type: string counts: type: object additionalProperties: {} metrics: type: object properties: error_rate: type: number nullable: true description: >- (4xx + 5xx) / total over the merged sources, 0..1; null when total is 0. avg_duration_ms: type: integer nullable: true description: >- Mean wall time of the rows that carry a duration; null when none. first_occurred_at: type: string nullable: true description: Earliest request in the window, ISO 8601 UTC. last_occurred_at: type: string nullable: true description: >- Latest request in the window: "when did my agent last call". required: - error_rate - avg_duration_ms - first_occurred_at - last_occurred_at required: - key - counts - metrics series: type: object properties: bucket: type: string enum: - hour - day points: type: array items: type: object properties: start: type: string description: The bucket start, ISO 8601 UTC. counts: type: object properties: total_count: type: integer error_count: type: integer groups: type: object properties: status_family: type: object additionalProperties: type: integer required: - status_family required: - total_count - error_count - groups groups: type: object additionalProperties: type: object properties: total_count: type: integer error_count: type: integer required: - total_count - error_count description: >- Per group_by key, this bucket only; empty when no group_by was passed. required: - start - counts - groups required: - bucket - points description: Present only when bucket was passed. applied_filters: type: object additionalProperties: {} meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: string nullable: true description: >- The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: string nullable: true description: >- user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - operation - metrics - meta McpError: type: object properties: success: type: boolean enum: - false error: type: object properties: code: type: string enum: - validation_failed - nothing_to_update - not_found - relation_not_found - invalid_transition - limit_exceeded - payment_required - duplicate_rejected - conflict - delete_blocked - unauthorized - forbidden - rate_limited - internal_error - service_unavailable - not_implemented message: type: string recoverable: type: boolean suggestion: type: string field_errors: type: object additionalProperties: type: array items: type: object properties: rule: type: string message: type: string required: - rule - message blockers: type: array items: type: object properties: type: type: string description: >- Machine-readable blocker type (active_flow, pending_tasks, …). severity: type: string enum: - hard - soft description: >- hard = external action required; soft = acknowledge is enough. description: type: string entity_sid: type: string nullable: true count: type: integer resolution: type: string description: 'Hard: tool name to call. Soft: code for acknowledge[].' resolution_hint: type: string required: - type - severity - description - entity_sid - resolution - resolution_hint context: type: object additionalProperties: {} required: - code - message - recoverable meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: string nullable: true description: >- The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: string nullable: true description: >- user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - error responses: McpClientError: description: >- MCP error envelope. `error.code` is one of validation_failed, nothing_to_update, not_found, relation_not_found, invalid_transition, limit_exceeded, payment_required, duplicate_rejected, conflict, delete_blocked, unauthorized, forbidden, rate_limited, not_implemented. content: application/json: schema: $ref: '#/components/schemas/McpError' McpServerError: description: >- MCP error envelope with `error.code` internal_error or service_unavailable. content: application/json: schema: $ref: '#/components/schemas/McpError' securitySchemes: BearerJwt: type: http scheme: bearer bearerFormat: JWT description: >- Access token issued by gtm.service.id. Its `access_identity` claim carries `team_sid`, `actor_sid` and `actor_type`, and that team scope is authoritative. TeamSid: type: apiKey in: header name: Team-SID description: >- Team scope for tokens that do not carry one. Ignored when the token already names a team. ````