Analytics REST API

How to access your analytics data with the REST API.

Before you begin

API Connect REST API calls are authenticated by using a bearer token in the authorization header. Use the toolkit credentials to request a bearer token. Toolkit credentials can be found in the API Manager UI:
  1. Log in to the API Manager UI.
  2. From the home page, click the Download toolkit tile.
  3. Download the Toolkit credentials.
  4. Open the downloaded credentials.json file:
    ...
  "toolkit": {
    "endpoint": "https://mgmt.api.example.com/api",
    "client_id": "7409693f-f726-48b4-8909-7c0d26f13e81",
    "client_secret": "5feeb0be-17f8-41a4-96d6-d40f33d69ef6"
  },
...
    Take note of the toolkit.client_id, toolkit.client_secret, and toolkit.endpoint from this file. You use these values to get your bearer token.

Procedure

  1. Use your credentials to request a bearer token: 
    curl -k -X POST -d '{"username": "<username>", "password": "<password>", "realm": "<realm>", "client_id": "<client_id>", "client_secret": "<client_secret>", "grant_type": "password"}' -H 'Content-Type: application/json' -H 'Accept: application/json' https://<platform api endpoint>/token
    Where:
    • <username> is the provider org owner.
    • <password> is the password for the specified <username>.
    • <realm> is the user registry realm for the specified <username>. By default the realm for provider organization owners is provider/default-idp-2.
    • <client_id> is the client ID from the "toolkit" section of the credentials.json file, or as provided by your API Connect cloud administrator.
    • <client_secret> is the client secret from the "toolkit" section of the credentials.json file, or as provided by your API Connect cloud administrator.
    • <platform api endpoint> is the platform API endpoint from the "toolkit" section of the credentials.json file, or as provided by your API Connect cloud administrator. It might have the path api appended to it, so full string is: https://<platform api endpoint>/api/token
    The bearer token is returned in the access_token property:
    {
    "access_token": "<bearer_token>",
    "token_type": "Bearer",
    "expires_in": 28800
}

    Note the expires_in value, which is the number of seconds before the token expires. After expiry, you must request a new bearer token.

  2. Use the returned bearer token to call the analytics REST API: 
    # This call to /orgs/<provider_organization>/events requires a bearer token that was requested with provider org credentials:
curl -k -H 'Authorization: Bearer <bearer_token>' -X GET --url 'https://<platform api endpoint>/analytics/<analytics_service>/orgs/<provider_organization>/events'

{
    "total": 300,
    "search_time": 3,
    "events": [...]
}

# This call to the consumer API: orgs/<consumer org>/dashboard, requires a bearer token that was requested with consumer org credentials.
curl -k -H 'X-IBM-Consumer-Context: <provider org>.<catalog>' -H 'Authorization: Bearer <bearer_token>' -X GET --url 'https://<consumer api endpoint>/consumer-analytics/orgs/<consumer org>/dashboard' 
{
    "search_time": 16,
    "status_codes": {
        "total": 300,
        "data": [...]
    },
    "min_response_time": {
        "data": ...
    ...
    Where:
    • <platform api endpoint> is the toolkit.endpoint, but with the /api at the end replaced with /analytics to access the analytics APIs.
    • <analytics_service> is the name of the analytics service.
    • <bearer_token> is the token from step 1. Do not wrap the token with quotation marks.
  3. Use query parameters to filter your results and display only certain fields.
    If you want to search for specific analytics event records, then append query parameters to the API call. For example, to get only event data for calls to a specific API and product:
    /events?api_name=<api name>&product_name=<product name>
    To get only certain API event record fields in the output, then append the fields query parameter. For example, to get only the API name and the time of the call:
    /events?fields=api_name,datetime
    To request only events before or after a certain time, use the start and end parameters. For example:
    /events?start=2024-07-11T10:01:00.000Z&end=2024-07-11T10:02:00.000Z

What to do next

Complete documentation of the analytics REST API is here: Analytics REST API.