API
TrainingSupportCommunity

common/apis/usage-details

The following shows how to generate the common/apis/usage-details report with the Generate a report POST operation of the Reporting API v2. See also other available reports.

Report definition

Provides audit details of latest individual API calls.

Data available for: 92 days

Available dimensions

Dimension nameDescriptionConfiguration
timestampDate and time of receiving an API request (UTC).type: TIMESTAMP_SEC
filterable: false
mandatory: false
filterType: TEXT
authorizable: false
clientOwnerUsername of the client owner.type: STRING
filterable: true
mandatory: false
filterType: TEXT
authorizable: false
clientIpIP generating an API request.type: STRING
filterable: true
mandatory: false
filterType: TEXT
authorizable: false
clientIdID of a client generating an API request.type: STRING
filterable: true
mandatory: false
filterType: TEXT
authorizable: false
authorizationClientTokenClient token used for generating an API request.type: STRING
filterable: true
mandatory: false
filterType: TEXT
authorizable: false
requestMethodA request method indicating the action performed on a resource.type: STRING
filterable: true
mandatory: false
filterType: ENUM
filterEnumValues: HEAD, GET, POST, OTHER, PUT, DELETE
authorizable: false
endpointA specific API configuration.type: STRING
filterable: true
mandatory: false
filterType: TEXT
authorizable: false
requestUriA URI of an API request.type: STRING
filterable: true
mandatory: false
filterType: TEXT
authorizable: false
responseStatusAn indicator of whether the HTTP response resulted in a success or an error.type: STRING
filterable: true
mandatory: false
filterType: ENUM
filterEnumValues: error, success
authorizable: false
responseClassA class of HTTP response status codes. For example, 2xx.type: STRING
filterable: true
mandatory: false
filterType: ENUM
filterEnumValues: 0xx, 1xx, 2xx, 3xx, 4xx, 5xx, 6xx, other
authorizable: false
responseCodeAn HTTP response status code. For example, 200.type: LONG
filterable: true
mandatory: false
filterType: TEXT
authorizable: false
accountIdCustomer account identifier linked to an API request.type: STRING
filterable: true
mandatory: false
filterType: TEXT
authorizable: true
contractTypeContract type identifier associated with an API client.type: STRING
filterable: true
mandatory: false
filterType: TEXT
authorizable: true

Generate a report

Use the Generate a report POST operation to execute a report.

Follow the API workflows to:

📘

This report doesn't support SortBys

You can't define SortBys in a request body for this report. The report always shows all available dimensions, without any custom sorting.

POST request sample

POST /reporting-api/v2/reports/common/apis/usage-details/data?timeRange=LAST_3_HOURS

Available time ranges

For this report, you can use these predefined ranges in the timeRange query parameter:

  • LAST_15_MINUTES

  • LAST_30_MINUTES

  • LAST_1_HOUR

  • LAST_3_HOURS

  • LAST_6_HOURS

  • LAST_12_HOURS

  • LAST_1_DAY

  • LAST_2_DAYS

  • LAST_1_WEEK

  • LAST_30_DAYS

  • LAST_90_DAYS

Supported filters

This report supports filtering by dimensions.

You can filter by each dimension that is labeled as filterable: true in the report options. See how to use filters.

Request body example

{
    "filters": [
        {
            "dimensionName": "responseCode",
            "operator": "IN_LIST",
            "expressions": [
                500,
                100
            ]
        },
        {
            "dimensionName": "contractType",
            "operator": "IN_LIST",
            "expressions": [
                "1-6T5ZND"
            ]
        }
    ],
    "limit": 1000
}

Default values

These default values apply to all requests, meaning they are used unless you specify otherwise.

  • Time range:

    • start = now - 3 hours
    • end = now

  • Dimensions:

    • timestamp
    • clientOwner
    • clientIp
    • clientId
    • authorizationClientToken
    • requestMethod
    • endpoint
    • requestUri
    • responseStatus
    • responseClass
    • responseCode
    • accountId
    • contractType

  • Filters:

    • accountId. You can use all account IDs to which you are authorized in ​Control Center​. If you don't specify any account ID in your request, the report shows data for all your available account IDs.
    • contractType. You can use all contract types to which you are authorized in ​Control Center​. If you don't specify any contract types in your request, the report shows data for all your available contract types.

  • SortBys:

    • timestamp, DESCENDING

Limits

Each report has some configured limits. If your request has values that exceed the limits, it results in an HTTP 400 Bad Request response. This report has the following limits:

SettingLimit
Maximum number of dimensions0
Maximum time range92 days
Maximum retention of historic data92 days
Maximum length of value for TEXT filters100
Maximum number of data points returned25000

Rate limiting

This report uses both cost-based and hit-based rate limiting. For the hit-based rate limiting, the limit for an account is 10 requests per minute.

In the asynchronous flow, you can have 3 queued POST requests at the same time.

Read more about the rate limiting.

Get report options

To get the report metadata through the API, run the Get report options operation.

GET /reporting-api/v2/reports/common/apis/usage-details

The response shows the list of available metrics and dimensions, the default values, and configured limits.

{
    "name": "API usage details report data",
    "description": "Provides audit details of latest individual API calls.",
    "status": "PUBLISHED",
    "metrics": [],
    "dimensions": [
        {
            "name": "timestamp",
            "description": "Date and time of receiving an API request (UTC).",
            "type": "TIMESTAMP_SEC",
            "filterable": false,
            "mandatory": false,
            "filterType": "TEXT",
            "authorizable": false
        },
        {
            "name": "clientOwner",
            "description": "Username of the client owner.",
            "type": "STRING",
            "filterable": true,
            "mandatory": false,
            "filterType": "TEXT",
            "authorizable": false
        },
        {
            "name": "clientIp",
            "description": "IP generating an API request.",
            "type": "STRING",
            "filterable": true,
            "mandatory": false,
            "filterType": "TEXT",
            "authorizable": false
        },
        {
            "name": "clientId",
            "description": "ID of a client generating an API request.",
            "type": "STRING",
            "filterable": true,
            "mandatory": false,
            "filterType": "TEXT",
            "authorizable": false
        },
        {
            "name": "authorizationClientToken",
            "description": "Client token used for generating an API request.",
            "type": "STRING",
            "filterable": true,
            "mandatory": false,
            "filterType": "TEXT",
            "authorizable": false
        },
        {
            "name": "requestMethod",
            "description": "A request method indicating the action performed on a resource.",
            "type": "STRING",
            "filterable": true,
            "mandatory": false,
            "filterType": "ENUM",
            "filterEnumValues": [
                "HEAD",
                "GET",
                "POST",
                "OTHER",
                "PUT",
                "DELETE"
            ],
            "authorizable": false
        },
        {
            "name": "endpoint",
            "description": "A specific API configuration.",
            "type": "STRING",
            "filterable": true,
            "mandatory": false,
            "filterType": "TEXT",
            "authorizable": false
        },
        {
            "name": "requestUri",
            "description": "A URI of an API request.",
            "type": "STRING",
            "filterable": true,
            "mandatory": false,
            "filterType": "TEXT",
            "authorizable": false
        },
        {
            "name": "responseStatus",
            "description": "An indicator of whether the HTTP response resulted in success or an error.",
            "type": "STRING",
            "filterable": true,
            "mandatory": false,
            "filterType": "ENUM",
            "filterEnumValues": [
                "error",
                "success"
            ],
            "authorizable": false
        },
        {
            "name": "responseClass",
            "description": "A class of HTTP response status codes. For example, 2xx.",
            "type": "STRING",
            "filterable": true,
            "mandatory": false,
            "filterType": "ENUM",
            "filterEnumValues": [
                "0xx",
                "1xx",
                "2xx",
                "3xx",
                "4xx",
                "5xx",
                "6xx",
                "other"
            ],
            "authorizable": false
        },
        {
            "name": "responseCode",
            "description": "An HTTP response status code. For example, 200.",
            "type": "LONG",
            "filterable": true,
            "mandatory": false,
            "filterType": "TEXT",
            "authorizable": false
        },
        {
            "name": "accountId",
            "description": "Customer account identifier linked to an API request.",
            "type": "STRING",
            "filterable": true,
            "mandatory": false,
            "filterType": "TEXT",
            "authorizable": true
        },
        {
            "name": "contractType",
            "description": "Contract type identifier associated with an API client.",
            "type": "STRING",
            "filterable": true,
            "mandatory": false,
            "filterType": "TEXT",
            "authorizable": true
        }
    ],
    "predefinedTimeRanges": [
        "LAST_15_MINUTES",
        "LAST_30_MINUTES",
        "LAST_1_HOUR",
        "LAST_3_HOURS",
        "LAST_6_HOURS",
        "LAST_12_HOURS",
        "LAST_1_DAY",
        "LAST_2_DAYS",
        "LAST_1_WEEK",
        "LAST_30_DAYS",
        "LAST_90_DAYS"
    ],
    "defaults": {
        "defaultTimeRange": {
            "start": "now - 3 hours",
            "end": "now"
        },
        "defaultDimensions": [
            "timestamp",
            "clientOwner",
            "clientIp",
            "clientId",
            "authorizationClientToken",
            "requestMethod",
            "endpoint",
            "requestUri",
            "responseStatus",
            "responseClass",
            "responseCode",
            "accountId",
            "contractType"
        ],
        "defaultSortBys": [
            {
                "name": "timestamp",
                "sortOrder": "DESCENDING"
            }
        ]
    },
    "limits": {
        "maxDimensions": 0,
        "maxDateRangeInDays": 92,
        "maxRetentionInDays": 92,
        "textFilterMaxLength": 100,
        "dataPointsLimit": 25000
    },
    "links": [
        {
            "rel": "self",
            "allow": [
                "GET"
            ],
            "href": "/reporting-api/v2/reports/common/apis/usage-details",
            "describedBy": "/reporting-api/v2/reports/schema"
        },
        {
            "rel": "data",
            "allow": [
                "POST"
            ],
            "href": "/reporting-api/v2/reports/common/apis/usage-details/data"
        }
    ]
}