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.

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
Endpoint https://call-trace-api.socrate.io/graphql
Required access keys Tenant-level service access key
Pricing Please contact us for details at contact@bitsoftware.ro
Notes To call the service, the access key must be provided in the x-api-key header of the HTTP request. If you are using the GraphQL console, you can view the service’s documentation and schema only after entering an access key. Make sure that the scope of the key allows access to the queries and mutations that you require. For example, to grant the key access to all queries and mutations, the keys’s scope must be set to call-trace-api:query:* call-trace-api:mutation:*.

Queries

calls

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

Arguments

Argument Type Description
filter CallsFilter! Provides filtering options to the query.
nextToken String Optional argument used to fetch the next set of query results. This value can be obtained from the nextToken attribute of the CallsResult type.
CallsFilter input
Attribute Type Description
from DateTime! Mandatory. The date and time starting with which call trace data will be fetched.
to DateTime Optional. The date and time up to which call trace will be fetched, for example, 2024-07-16, 2024-07-15T06:59:59, 2024-07-16T11:30:53.983Z. Note that, if you specify only a date value without time, then the time is considered to be 00:00:00.
service ServiceCode Optional. The service code specifies the service for which you would like to collect call trace data. To obtain all available service codes, run the services query.
operationType OperationType Optional. Specifies the operation type for which call trace data should be returned. Valid values: query, mutation.
result CallResult Optional. Lets you filter calls by result type. Valid values: data - return calls with data, error- return calls with errors.
field Field Optional. Specifies the name of the query or mutation for which call trace data should be returned.
publicKey ID Optional. Lets you filter calls where a tenant-level service access key (not a token) was used and the public key is the one you supply in this input parameter.
userId ID Optional. Lets you filter calls initiated by a specific SBS Portal User. To filter such calls, supply the ID of the portal user in this input parameter. You can find the ID of an SBS Portal User by running the portalUsers query of the Account API.

Result

CallsResult type
Attribute Type Description
items [CallsValue] The call trace data that matches the filtering options, as an array of items of type CallsValue.
nextToken String If null, then the query has reached the end of the list of results that match the query criteria. If not null, then use this value in the nextToken input argument, with the same filter, to fetch the next set of results.
CallsValue type
Attribute Type Description
service ServiceCode The service code indicates specifies the service for which call trace data have been retrieved.
operationType OperationType Specifies the operation type for which call trace data have been returned. Valid values: query, mutation.
field Field Specifies the name of the query or mutation for which call trace data have been retrieved.
count Float The actual count of calls (queries or mutations) that took place.
duration Float The call duration, in milliseconds.

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

Argument Type Description
filter DistinctCallsFilter! Provides filtering options to the query.
nextToken String Optional argument used to fetch the next set of query results. This value can be obtained from the nextToken attribute of the CallsResult type.
DistinctCallsFilter input
Attribute Type Description
from DateTime! Mandatory. The date and time starting with which call records will be fetched.
to DateTime Optional. The date and time up to which call records will be fetched, for example, 2024-07-16, 2024-07-15T06:59:59, 2024-07-16T11:30:53.983Z. Note that, if you specify only a date value without time, then the time is considered to be 00:00:00.
service ServiceCode Optional. The service code specifies the service for which you would like to retrieve calls. To obtain all available service codes, run the services query.
operationType OperationType Optional. Specifies the operation type for which call records should be returned. Valid values: query, mutation.
field Field Optional. Specifies the name of the query or mutation for which call records should be returned.
publicKey ID Optional. Lets you filter calls where a tenant-level service access key (not a token) was used and the public key is the one you supply in this input parameter.
userId ID Optional. Lets you filter calls initiated by a specific SBS Portal User. To filter such calls, supply the ID of the portal user in this input parameter. You can find the ID of an SBS Portal User by running the portalUsers query of the Account API.
requestId ID Optional. Lets you filter calls by the unique request ID assigned to this call by AWS.
result CallResult Optional. Lets you filter calls by result type. Valid values: data - return calls with data, error- return calls with errors.

Result

DistinctCallsResult type
Attribute Type Description
items [DistinctCallsValue] The data that matches the filtering options, as an array of items of type DistinctCallsValue.
nextToken String If null, then the query has reached the end of the list of results that match the query criteria. If not null, then use this value in the nextToken input argument, with the same filter, to fetch the next set of results.
DistinctCallsValue type
Attribute Type Description
service ServiceCode The service code indicates specifies the service for which call records have been retrieved.
operationType OperationType Specifies the operation type for which call records have been returned. Valid values: query, mutation.
field Field Specifies the name of the query or mutation for which call records have been retrieved.
publicKey ID The public key with which the call was made. Applicable only for calls that were made through an API key.
userId ID The ID of the user in User Management Service that made this call through the SBS Portal. Applicable only for calls that were made through an authorization token by SBS Portal users.
requestId ID The unique identifier of the request assigned by AWS.
result CallResult Indicates whether the call returned data or an error. Valid values: data, error.
message String The error message. This value is present only if the call result was error.
duration Float The call duration, in milliseconds.
time DateTime The date and time when the call took place.

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"
  }
}

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.

Read more

Authorization Service Document Log Service