API
TrainingSupportCommunity

common/apis/usage

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

Report definition

Provides requests and volume for API traffic.

Data available for: 123 days

Available metrics

Metric nameDescriptionConfiguration
requestsSumThe total number of API requests.type: LONG
filterable: true
mandatory: false
requestsPercentageThe percentage of API requests.type: DOUBLE
filterable: true
mandatory: false
bytesSumThe total volume of API requests.type: LONG
filterable: true
mandatory: false
bytesPercentageThe percentage of volume of API requests.type: DOUBLE
filterable: true
mandatory: false

Available dimensions

Dimension nameDescriptionConfiguration
time1hourDatapoint timestamp for 1 hour granularity.type: TIMESTAMP_SEC
filterable: false
mandatory: false
filterType: TEXT
authorizable: false
time1dayDatapoint timestamp for 1 day granularity.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
clientIdID of a client generating an API request.type: STRING
filterable: true
mandatory: false
filterType: TEXT
authorizable: false
endpointA specific API configuration.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
agentFamilyFamily of the API client used.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:

POST request sample

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

Available time ranges

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

  • LAST_1_HOUR

  • LAST_1_DAY

  • LAST_2_DAYS

  • LAST_1_WEEK

  • LAST_30_DAYS

Supported filters

This report supports filtering by dimensions and metrics.

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

Request body example

{
    "dimensions": [
        "responseCode",
        "time1hour",
        "time1day",
        "requestMethod"
    ],
    "metrics": [
        "requestsSum",
        "requestsPercentage",
        "bytesSum",
        "bytesPercentage"
    ],
    "filters": [
        {
            "dimensionName": "accountId",
            "operator": "IN_LIST",
            "expressions": [
                "1-511C"
            ]
        },
        {
            "dimensionName": "requestMethod",
            "operator": "IN_LIST",
            "expressions": [
                "HEAD",
                "GET"
            ]
        },
        {
            "metricName": "requestsSum",
            "operator": "NOT_EQUAL",
            "expression": 350
        },
        {
            "metricName": "bytesSum",
            "operator": "LESS_THAN",
            "expression": 1238
        }
    ],
    "sortBys": [
        {
            "name": "bytesPercentage",
            "sortOrder": "ASCENDING"
        }
    ],
    "limit": 1000
}

Default values

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

  • Time range:

    • start = now - 1 day
    • end = now

  • Metrics:

    • requestsSum
    • requestsPercentage
    • bytesSum
    • bytesPercentage

  • Dimensions:

    • endpoint

  • 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:

    • requestsSum, 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 dimensions4
Maximum time range123 days
Maximum retention of historic data123 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

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

{
    "name": "API usage report data",
    "description": "Provides requests and volume for API traffic.",
    "status": "PUBLISHED",
    "metrics": [
        {
            "name": "requestsSum",
            "description": "The total number of API requests.",
            "type": "LONG",
            "filterable": true,
            "mandatory": false
        },
        {
            "name": "requestsPercentage",
            "description": "The percentage of API requests.",
            "type": "DOUBLE",
            "filterable": true,
            "mandatory": false
        },
        {
            "name": "bytesSum",
            "description": "The total volume of API requests.",
            "type": "LONG",
            "filterable": true,
            "mandatory": false
        },
        {
            "name": "bytesPercentage",
            "description": "The percentage of volume of API requests.",
            "type": "DOUBLE",
            "filterable": true,
            "mandatory": false
        }
    ],
    "dimensions": [
        {
            "name": "time1hour",
            "description": "Datapoint timestamp for 1 hour granularity.",
            "type": "TIMESTAMP_SEC",
            "filterable": false,
            "mandatory": false,
            "filterType": "TEXT",
            "authorizable": false
        },
        {
            "name": "time1day",
            "description": "Datapoint timestamp for 1 day granularity.",
            "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": "clientId",
            "description": "ID of a client generating an API request.",
            "type": "STRING",
            "filterable": true,
            "mandatory": false,
            "filterType": "TEXT",
            "authorizable": false
        },
        {
            "name": "endpoint",
            "description": "A specific API configuration.",
            "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": "agentFamily",
            "description": "Family of the API client used.",
            "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_1_HOUR",
        "LAST_1_DAY",
        "LAST_2_DAYS",
        "LAST_1_WEEK",
        "LAST_30_DAYS"
    ],
    "defaults": {
        "defaultTimeRange": {
            "start": "now - 1 day",
            "end": "now"
        },
        "defaultMetrics": [
            "requestsSum",
            "requestsPercentage",
            "bytesSum",
            "bytesPercentage"
        ],
        "defaultDimensions": [
            "endpoint"
        ],
        "defaultSortBys": [
            {
                "name": "requestsSum",
                "sortOrder": "DESCENDING"
            }
        ]
    },
    "limits": {
        "maxDimensions": 4,
        "maxDateRangeInDays": 123,
        "maxRetentionInDays": 123,
        "textFilterMaxLength": 100,
        "dataPointsLimit": 25000
    },
    "links": [
        {
            "rel": "self",
            "allow": [
                "GET"
            ],
            "href": "/reporting-api/v2/reports/common/apis/usage",
            "describedBy": "/reporting-api/v2/reports/schema"
        },
        {
            "rel": "data",
            "allow": [
                "POST"
            ],
            "href": "/reporting-api/v2/reports/common/apis/usage/data"
        }
    ]
}