Required Subscription: Enterprise Module

Required Permission Level: Administrator

Brightmetrics is happy to bring more options to our customers for ways to export the data found in the user interface for use in data access tools like Tableau, Microsoft's Power BI, and others.  To do this we've established an OData feed.  

Our OData/API Export offering is a part of our Enterprise module. If you don’t see the option to set up a report API URL, please reach out to our Support team for details by emailing us at support@brightmetrics.com.

Table of Contents

• Addressing and Access
• Authentication
• Requesting Data
• Filtering
• Asynchronous export
• API Limit

Addressing and Access:

If you use a data access tool that supports connecting to OData v4 data sources, you can connect to the URL https://webapp.brightmetrics.com/OData.ashx

If you are exporting data from an individual report directly, not using OData, the URL for each individual report is available in the Brightmetrics user interface, here on your saved report:

• Choose Reports from the left sidebar menu
• Choose the Report template you wish to export and make any modifications
• Choose Save As on top and give your report a name and description and then choose Okay to Save the report
• Access the 3 dots menu on top and choose API

This document explains how to use the API, but for the full OData specification please refer to https://www.odata.org/documentation/

Authentication:

There are two supported authentication mechanisms: username and password (basic), and API key.

For basic username and password authentication, the username is the email address that you use to log in to Brightmetrics. There are two ways to provide a password. In order to avoid the need to store the password itself in any configuration files or scripts, you can instead provide a SHA256 hash of the password, base64 encoded. There are many web-based and other utilities that can do this for you, but here are two native ways to do this from the command line on either Windows or Linux and Macos that you can copy and paste, replacing "password" with your own password.

Windows (Powershell):

   [System.Convert]::ToBase64String([System.Security.Cryptography.SHA256]::Create().ComputeHash([System.Text.Encoding]::UTF8.GetBytes("password")))

Macos/Linux (Terminal):

   echo -n "password" |openssl sha256 -binary |openssl base64

Alternatively, you can include the password itself directly by prefixing it with *pass. So for example, if your password is abcd1234, you can provide it either as *passabcd1234, or as the encoded value 6c7nGrky/ehjM40Ivk3p3+OeoEm9r7NCzmWexUULaa4=

For example:

curl -u "user@example.com:*passpassword" https://webapp.brightmetrics.com/OData.ashx

or

curl -u "user@example.com:XohImNooBHFR0OVvjcYpJ3NgPQ1qq73WKhHvch0VQtg=" https://webapp.brightmetrics.com/OData.ashx

For API key authentication, you can retrieve and manage your personal API key on the "My Account" page in Brightmetrics.  This will be auto-generated when your account is enabled for OData usage.  This should not be shared with anyone and is specific to your account:

The API key should be passed as a Bearer token in the HTTP Authorization header, for example:

curl -H "Authorization: Bearer 4df21f67c293413fa988d8f1535cd12f" https://webapp.brightmetrics.com/OData.ashx

In order to support applications that do not support Bearer token as an authentication method (for example PowerBI), you can also choose Basic authentication and use the special user name apikey with the API key as the password.

Requesting data

If you use a data access tool (e.g PowerBI or Tableau) that supports OData v4, requesting data will be handled internally and you will not need to know the details. But if you are requesting data using another tool or script for which you need to compose the requests yourself, these are the details for doing so.

Listing available data views

Each saved report that you have access to via the web UI is available for export via the API.

You can find the URL for each report in the Brightmetrics UI, from the report context menu. You can also discover what reports are available programmatically by requesting the OData Service Document from the OData root URL https://webapp.brightmetrics.com/OData.ashx:

curl -u "user@example.com:*passpassword" https://webapp.brightmetrics.com/OData.ashx

{
  "@odata.context": "https://webapp.brightmetrics.com/$metadata",
  "value": [
    {
      "name": "Service_Summary_03bd1235eb2c410fa415fefacd98df41",
      "title": "Service Summary",
      "kind": "EntitySet",
      "url": "03bd1235-eb2c-410f-a415-fefacd98df41"
    },
    {
      "name": "Agent_Activity_Summary___All__Saved_MSC_Agents__041cee41ac5f4455a02d022705afe417",
      "title": "Agent Activity Summary - All (Saved MSC Agents)",
      "kind": "EntitySet",
      "url": "041cee41-ac5f-4455-a02d-022705afe417"
    },
    {
      "name": "Helpdesk_Workgroup_Service_Level_Summary_w_o_Wait_Time_0c15c8a5128b488b8758ef15868c3b5b",
      "title": "Helpdesk Workgroup Service-Level Summary w/o Wait Time",
      "kind": "EntitySet",
      "url": "0c15c8a5-128b-488b-8758-ef15868c3b5b"
    }
}

The "title" of the report will match what you see in the Brightmetrics reporting interface. The "url" is the URL relative to the OData root URL from which the report data can be requested. The "name" is a combination of the two formatted in a manner required by the OData specification. All are "entity sets" in OData terminology.

Retrieving report data

Whether the report URL has been located from the service document as above, or directly from the web UI, the data for that particular report can be requested by sending a request to the report URL, for example:

curl -u "user@example.com:*passpassword" https://webapp.brightmetrics.com/OData.ashx/0c15c8a5-128b-488b-8758-ef15868c3b5b

By default, the data will be returned in JSON format, in the OData conventional representation. If you would like the data in a different format, that can be requested by providing the appropriate media type in the HTTP Accept header. For example, to get the data as unformatted CSV:

curl -u "user@example.com:*passpassword" https://webapp.brightmetrics.com/OData.ashx/0c15c8a5-128b-488b-8758-ef15868c3b5b -H "Accept: text/csv"

The supported media types are:

The format can also be requested via the url parameter $format. For example:

curl -u "user@example.com:*passpassword" "https://webapp.brightmetrics.com/OData.ashx/0c15c8a5-128b-488b-8758-ef15868c3b5b?$format=csv"

The supported formats this way are:

Filtering

If no filters are supplied, the results will be the same as would be presented in the Brightmetrics web interface if one were to open the report and run it without changing any of the configured filters. However, it is possible to supply alternate values for any unlocked filter configured on the report, in the same way, that schedules for reports can provide unique per-schedule options for any filter configured on the report. 

Filters can be provided in a query parameter named $filter. Please refer to the Querying Collections section here of the OData protocol documentation for a complete reference. Supported filter operations are described below.

As an example, if Queue Name is a filter on the report, a queue name filter can be specified with the query string Queue_Name eq 'Customer Service' or Queue_Name in ('Customer Service', 'Sales'). Notice that the space in "Queue Name" been replaced with an underscore in order to comply with OData identifier restrictions. Any character that is not a letter or a number will be replaced with an underscore, but never more than one. So for example Time - Call - Total becomes Time_Call_Total, rather than Time___Call___Total.

Supported filter operators are:

In addition, filters can be combined with and, for example: $filter=Call_Date_Time ge 2020-05-01T00:00:00Z and Call_Date_Time le 2020-05-31T23:59:59Z and Queue_Name in ('Customer Service', 'Sales')

Please note that aside from ge/le pairs, the same property can not be listed more than once. Greater Than and Less Than filters should only be applied to dates and numbers. Equal and In filters should only be applied to text values.

The filter property names can generally be readily determined from the filter labels on the report using the replacement rules described, but a request can also be sent to a report-specific metadata endpoint to get the list of available filters. For example:

curl -u "user@example.com:*passpassword" 'https://webapp.brightmetrics.com/OData.ashx/6f40b845-fb28-4547-b73b-e11ce29f481b/$metadata'`

<?xml version="1.0" encoding="utf-8"?>
<edmx:Edmx Version="4.0" xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx">
    <edmx:DataServices>
        <Schema Namespace="Brightmetrics" xmlns="http://docs.oasis-open.org/odata/ns/edm">
            <EntityType Name="filters_6f40b845-fb28-4547-b73b-e11ce29f481b">
                <Property Name="Call_Date_Time" Type="Edm.DateTimeOffset" />
                <Property Name="Media_Type" Type="Edm.String" />
                <Property Name="Agent_Name" Type="Edm.String" />
                <Property Name="Agent_Name_by_Queue_Membership" Type="Edm.String" />
                <Property Name="Agent_Name_by_Skill" Type="Edm.String" />
                <Property Name="Agent_Name_by_Group_Membership" Type="Edm.String" />
                <Property Name="Time_Talk_Total" Type="Edm.Double" />
            </EntityType>
            <EntityContainer Name="Saved Reports">
                <EntitySet Name="Agent_Detail_6f40b845fb284547b73be11ce29f481b_filters" EntityType="Brightmetrics.filters_6f40b845-fb28-4547-b73b-e11ce29f481b" />
            </EntityContainer>
        </Schema>
    </edmx:DataServices>
</edmx:Edmx>

This reveals that the available filters are Call_Date_Time, which is a DateTimeOffset value, meaning it can be specified in ISO8601 format like YYYY-MM-DDTHH:mm:ssZ; Media_Type, which is a string (text) value, and so forth.

Agent_Name is listed a few times -- these correspond to the filter options in the UI to filter agent names by "proxy", such as by belonging to a particular queue or possessing a certain skill. Be aware that these are still all "Agent Name" filters and therefore can not be combined. For instance, a filter can not be provided for both Agent_Name and Agent_Name_by_Skill.

Asynchronous export

Requesting a lot of data, or a report covering a long range of time, especially detailed data, can take longer to come back with data than an HTTP client might be willing to wait, or the web server allows. Therefore, asynchronous exports are also supported, using the OData v4 mechanism specified for this purpose.

By including the HTTP header "Prefer: respond-async", the OData endpoint will return instead of the report data itself, a URL from which to retrieve the data when it is complete. That endpoint can be polled to check the status.

curl -i -u "user@example.com:*passpassword" https://webapp.brightmetrics.com/OData.ashx/0c15c8a5-128b-488b-8758-ef15868c3b5b -H "Prefer: respond-async"

HTTP/1.1 202 Accepted
Content-Type: application/json; odata.metadata=minimal; odata.streaming=true
Location: https://webapp.brightmetrics.com/OData.ashx/status/5854e5ec-0ad4-4da2-9329-7c1b0e8648ab
Retry-After: 5
OData-Version: 4.0
Content-Length: 99

{
  "statusUrl": "https://webapp.brightmetrics.com/OData.ashx/status/5854e5ec-0ad4-4da2-9329-7c1b0e8648ab"
}

The HTTP status code will be 202 Accepted, and the HTTP Location header, as well as the statusUrl property of the response body contains a URL from which to check the job status and retrieve the results.

Sending a request to the status URL while the job is still in progress will return the same 202 Accepted result:

curl -i -u "user@example.com:*passpassword" https://webapp.brightmetrics.com/OData.ashx/status/5854e5ec-0ad4-4da2-9329-7c1b0e8648ab -H "Prefer: respond-async"

HTTP/1.1 202 Accepted
Content-Type: application/json; odata.metadata=minimal; odata.streaming=true
Location: https://webapp.brightmetrics.com/OData.ashx/status/5854e5ec-0ad4-4da2-9329-7c1b0e8648ab
Retry-After: 5
OData-Version: 4.0
Content-Length: 99

{
  "statusUrl": "https://webapp.brightmetrics.com/OData.ashx/status/5854e5ec-0ad4-4da2-9329-7c1b0e8648ab"
}

Once the job is complete, it will return HTTP 200 Okay with the request body, the same as when requested directly. The status URL will remain valid for 1 hour.

Server-side paging

If data is requested in OData format for a detail report that covers a long time range, and asynchronous export was not requested, the query will be divided into smaller time ranges and a continuation token will be included with each (potentially empty) result set which the client can follow to request the next range of data until no more continuation token is provided.  This is called a "next link" in OData terminology and is contained in a property named @odata.nextLink as shown in the following example:

{
    "@odata.context":"https://webapp.brightmetrics.com/OData.ashx/$metadata#Search_by_CallerID_68c8e362b2c26f6d498baf782b253239",
    "@odata.nextLink":"https://webapp.brightmetrics.com/OData.ashx/68c8e362-b2c2-6f6d-498b-af782b253239?$skiptoken=eyJJZCI6IjFjOTIzOWM1LTQ0ZWItNDFiNS05M2U4LTcyMDRkYjQ1OGM5NCIsIk5leHRTdGFydCI6IjIwMjEtMDItMjZUMDA6MDA6MDBaIiwiRW5kIjoiMjAyMS0wNC0yNlQyMzo1OTo1OS45OTlaIn0%3D",
    "value":[
        {
            "Call_Date_Time":"2021-02-17T20:39:47.0000000Z",
            "Call_Type":"Inbound",
            "Action":"Transfer",
            "CallerID":"+15551238888",
            "Workgroup_Call":"Non-WG",
            "Trunk":"PRI (4)",
            "Dialed_Number":"15556781111",
            "Party_Name":"Front Counter Main",
            "Extension":"3001",
            "Call_Duration":2.2833
        }
    ]
}

Timezone

Note that that the following only applies to data sets that are timezone aware, which are Genesys Cloud and MiContact Center Business. This does not apply to MiVoice Connect or Connect Contact Center, which always use the native timezone of the data.

The default timezone is UTC. To indicate the timezone you'd like to use instead, append the following parameter to the generated URL provided in the Report API (do not include the "<>"):

?timezone=<timezoneName>

Example:

?timezone=Eastern%20Standard%20Time

Resulting in the full URL being something like:

https://webapp.brightmetrics.com/OData.ashx/xxxxxxx?timezone=Eastern%20Standard%20Time

Ensure that the spaces are escaped as in the example above with "%20".

Timezone options:

To get your current timezone, use the following in the Windows command prompt:

tzutil /g

For a full list of timezone options use:

tzutil /l

API Limits:

To keep our user experience great for everybody, we limit API requests from all users of a single company account to 150 requests in a 24-hour period. Abuse of the API feature can degrade the user experience for all users at your company.

While this has been put into place, we also understand that there may be cases where perfectly reasonable use of the API may exceed that limit.  For that reason, we have also added a button under the "My Account" section shown here below which will allow you to refresh/reset that limit.  See the example below:

We hope this helps with this new feature we are excited to bring to our customers! 

Questions or concerns? Please email us at support@brightmetrics.com.