openapi: 3.2.0 info: title: 'GTM API public contract: gtm.service.id API Requests API' 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.' 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: api_requests description: Registry package `mcp.id/api_requests`, served on MCP mount `id.platform`. paths: /api/api-requests/metrics: post: operationId: get_api_request_metrics 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", groups carry the client name), 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.' tags: - api_requests 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' x-gtm-mcp-tool: get_api_request_metrics x-gtm-mcp-mount: id.platform x-gtm-entity: api_requests x-gtm-operation: metrics x-gtm-envelope: metrics x-gtm-availability: ga x-gtm-dangerous: false x-gtm-mass-action: false x-gtm-step-eligible: false x-gtm-schedule-required: false x-gtm-tool-class: typical /api/api-requests/search: post: operationId: search_api_requests summary: Search API requests description: 'List the team''s external API requests newest first: every call made with an api key or an OAuth client (your own calls included), as logged by the service that answered it, merged across id, linkedin and orchestration. One row per request: the client (key or OAuth client, with its name), the route and entity, the HTTP status and its family, the typed error it failed with (error_code, error_reason, error_cause), the account it named, the duration, the trace id. Use for "what did our agents do", "show the failing requests since noon" (filter status_family in [4xx,5xx]), "why are these all 429" (filter error_cause: a paused account is not a spent daily limit), "what did the n8n client call" (filter client_sid), or one MCP turn (filter trace_id). page_size 0 counts only; the cursor is a keyset merged across services. counts.sources says which services answered; a service marked error contributed nothing. Not LinkedIn activity (that is the account activity log) and not a quota: the log counts, it never limits. Contract: - MCP tool `search_api_requests`, registry package `mcp.id/api_requests`, mount `id.platform`. - Operation `search`, response envelope `search`. - Flags: read only.' tags: - api_requests requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/SearchApiRequestsRequest' responses: '200': description: '`search` success envelope.' content: application/json: schema: $ref: '#/components/schemas/SearchApiRequestsResponse' 4XX: $ref: '#/components/responses/McpClientError' 5XX: $ref: '#/components/responses/McpServerError' x-gtm-mcp-tool: search_api_requests x-gtm-mcp-mount: id.platform x-gtm-entity: api_requests x-gtm-operation: search x-gtm-envelope: search x-gtm-availability: ga x-gtm-dangerous: false x-gtm-mass-action: false x-gtm-step-eligible: false x-gtm-schedule-required: false x-gtm-tool-class: typical components: schemas: SearchApiRequestsRequest: type: object description: Request body of `search_api_requests`. 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. sort: type: object properties: field: type: string enum: - occurred_at direction: type: string enum: - asc - desc description: Default desc. required: - field page_size: type: integer minimum: 0 maximum: 200 description: 0..200, default 50. page_size=0 = count-only, page_size=1 = getFirst. cursor: type: - string - 'null' description: Opaque forward cursor from a previous response pagination.next_cursor. 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 - 'null' 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 - 'null' 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 - 'null' 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 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 - 'null' description: (4xx + 5xx) / total over the merged sources, 0..1; null when total is 0. avg_duration_ms: type: - integer - 'null' description: Mean wall time of the rows that carry a duration; null when none. first_occurred_at: type: - string - 'null' description: Earliest request in the window, ISO 8601 UTC. last_occurred_at: type: - string - 'null' 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 label: type: string credential_kind: type: string enum: - api_key - oauth counts: type: object additionalProperties: {} metrics: type: object properties: error_rate: type: - number - 'null' description: (4xx + 5xx) / total over the merged sources, 0..1; null when total is 0. avg_duration_ms: type: - integer - 'null' description: Mean wall time of the rows that carry a duration; null when none. first_occurred_at: type: - string - 'null' description: Earliest request in the window, ISO 8601 UTC. last_occurred_at: type: - string - 'null' 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 - 'null' 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 - 'null' 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 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".' 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 SearchApiRequestsResponse: type: object properties: success: type: boolean enum: - true operation: type: string enum: - search items: type: array items: type: object properties: item: type: object properties: sid: type: string team_sid: type: string service: type: string enum: - id - linkedin - orchestration occurred_at: type: string surface: type: string enum: - api_key - agent - oauth_other credential_kind: type: string enum: - api_key - oauth client_sid: type: string client_name: type: - string - 'null' actor_sid: type: - string - 'null' method: type: string route: type: string entity: type: string operation: type: string enum: - get - search - metrics - group_by - create - update - delete - action action_name: type: - string - 'null' account_sid: type: - string - 'null' status: type: integer status_family: type: string enum: - 2xx - 3xx - 4xx - 5xx error_code: type: - string - 'null' error_reason: type: - string - 'null' error_cause: type: - string - 'null' duration_ms: type: - integer - 'null' trace_id: type: - string - 'null' required: - sid - team_sid - service - occurred_at - surface - credential_kind - client_sid - client_name - actor_sid - method - route - entity - operation - action_name - account_sid - status - status_family - error_code - error_reason - error_cause - duration_ms - trace_id included: type: object additionalProperties: {} required: - item - included pagination: type: object properties: next_cursor: type: - string - 'null' has_more: type: boolean total_count: type: - integer - 'null' required: - next_cursor - has_more - total_count applied_filters: type: object additionalProperties: {} includes: type: array items: type: string 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 - 'null' 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 - 'null' description: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms counts: type: object properties: total_count: type: integer sources: type: object additionalProperties: type: string enum: - ok - error - unconfigured description: 'Which services this answer counts: ok / error (did not answer, contributes nothing) / unconfigured. A service the `service` filter excludes is absent.' required: - total_count - sources required: - success - operation - items - pagination - applied_filters - includes - meta responses: McpServerError: description: MCP error envelope with `error.code` internal_error or service_unavailable. content: application/json: schema: $ref: '#/components/schemas/McpError' 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' 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.