Call Trace Service

The Call Trace Service enables callers to obtain information about all API calls that took place within a given time period. For example, you can view the count of queries or mutations of a particular service that were called within a given time period. The service also reports the outbound webhook deliveries that SBS attempted, through the webhookCalls query.

This service is a tenant-level service, and, consequently, it returns data only for other tenant-level services. To return the list of tenant-level services, run the services query.

To return call trace data for account-level services, or for the account-api service, run the calls query of the Account API.

Access info

Queries

calls

Returns the count of queries or mutations that were run for a particular service, or for all services.

Arguments

CallsFilter input

Result

CallsResult type

CallsValue type

Example

The following call returns the count of runs for the sendMessage mutation of the Email Service starting from the 1st of July 2023 up to the current date and time:

query calls ($filter:CallsFilter!){
  calls(filter:$filter) {
    items {
      service
      operationType
      field
      count
    }
  }
}

{
  "filter": {
    "from": "2023-07-01",
    "service": "email-api",
    "field": "sendMessage"
  }
}

distinctCalls

Returns more detailed trace information about API calls. Compared to the calls query, the distinctCalls query does not aggregate the count of calls, and thus is useful for debugging individual calls.

Arguments

DistinctCallsFilter input

Result

DistinctCallsResult type

DistinctCallsValue type

Example

The following call returns information about erroneous calls that took place for the Email Service on May 28th, 2025:

query distinctCalls ($filter:DistinctCallsFilter!, $nextToken:String) {
  distinctCalls(filter:$filter, nextToken:$nextToken) {
    items {
      service
      operationType
      field
      publicKey
      userId
      requestId
      result
      message
      duration
      time
    }
    nextToken
  }
}

{
  "filter": {
    "from": "2025-05-28",
    "to": "2025-05-29",
    "service": "email-api",
    "result": "error"
  }
}

webhookCalls

Returns the individual webhook deliveries that SBS attempted, so you can check whether a webhook your application expected was sent, and how your endpoint responded.

Results are scoped to the tenant of the access key that you use, so the query takes no tenant, account, or application argument. Deliveries are returned newest first.

For information about configuring webhooks, see Webhooks.

Arguments

WebhookCallsFilter input

Filtering options are combined conjunctively: a delivery is returned only if it matches every option that you supply.

Result

WebhookCallsResult type

WebhookCallValue type

Example

The following call returns the failed webhook deliveries raised by the Email Service between the 1st and the 8th of July 2026:

query webhookCalls ($filter:WebhookCallsFilter!, $nextToken:String) {
  webhookCalls(filter:$filter, nextToken:$nextToken) {
    items {
      timestamp
      service
      event
      webhookType
      httpMethod
      httpStatus
      duration
      result
      requestId
    }
    nextToken
  }
}

{
  "filter": {
    "from": "2026-07-01",
    "to": "2026-07-08",
    "service": "email-api",
    "result": "ERROR"
  }
}

services

Returns a list of all services exposed by the Socrate Business Services API. This query is useful when you need to find out the service code of a particular service, for example, when querying usage.

Arguments

None.

Result

An array of service codes.

Example

query services {
  services 
}

version

Returns the API version.

AI agent access (MCP)

The service serves its queries as tools to AI agent clients over the Model Context Protocol (MCP), a JSON-RPC 2.0 protocol through which a client reads a catalog of tools and calls them by name. Agent clients such as Claude Code connect to https://call-trace-api.socrate.io/mcp.

Access

The MCP endpoint is on the same host as the GraphQL endpoint and accepts the same credentials:

• A tenant-level service access key, in the x-api-key header.
• A service access token, in the Authorization header as Bearer YOUR_SERVICE_ACCESS_TOKEN.

The endpoint speaks protocol revision 2026-07-28 and accepts protocol requests as POST only. It is stateless: every request carries its own credentials, and there is no handshake or session to open first. Your agent client must support revision 2026-07-28.

For connection instructions, open https://call-trace-api.socrate.io/mcp in a browser. The page needs no credential.

Tools

The catalog holds one tool per query of this service:

The filter of each of these tools requires from. The optional nextToken argument of each query is an optional argument of its tool.

The catalog a caller receives lists only the tools whose query the scope of its key or token allows. If a service access denial blocks a query, your agent does not see a tool for it. A tool call runs the query under the caller’s own credentials and returns the data that the equivalent GraphQL query returns for that caller. Every tool is marked read-only (readOnlyHint is true), and answers from SBS alone, without calling any system outside SBS (openWorldHint is false).

Documentation resources

Besides its tools, the endpoint publishes, as addresses, this page and the API conventions page.

Connecting an agent client

To add the endpoint to Claude Code, run:

claude mcp add --transport http call-trace-api https://call-trace-api.socrate.io/mcp --header "x-api-key: YOUR_ACCESS_KEY"

Other agent clients take the same URL and header in their own configuration.

Example

An agent client builds the protocol requests for you. To call a tool directly over HTTP, send a POST request that names the protocol revision both in the MCP-Protocol-Version header and in the request’s _meta, the method in the Mcp-Method header, and, for a tool call, the tool in the Mcp-Name header:

POST /mcp HTTP/1.1
Host: call-trace-api.socrate.io
Content-Type: application/json
Accept: application/json
x-api-key: YOUR_ACCESS_KEY
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: calls

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {}
    },
    "name": "calls",
    "arguments": {
      "filter": {
        "from": "2026-10-01",
        "service": "email-api",
        "field": "sendMessage"
      }
    }
  }
}

The call trace data is returned in structuredContent, and as the same JSON text in content:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "complete",
    "content": [
      { "type": "text", "text": "{\"items\":[{\"service\":\"email-api\", ...}" }
    ],
    "structuredContent": {
      "items": [
        {
          "service": "email-api",
          "operationType": "mutation",
          "field": "sendMessage",
          "count": 42,
          "duration": 318.5
        }
      ],
      "nextToken": null
    }
  }
}