Exporting Using Brightmetrics API

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

Our OData/API Export offering is 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 at support@brightmetrics.com.

• Addressing and Access
• Authentication
• Requesting Data
• Filtering
• Asynchronous Export
• API Limits

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 on your saved report:

1. 1

   Choose Reports from the left sidebar menu.

2. 2

   Choose the report template you wish to export and make any modifications.

3. 3

   Choose Save As on top, give your report a name and description, and click Okay to save.

4. 4

   Access the 3 dots menu on top and choose API.

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

Authentication

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

For basic authentication, the username is the email address you use to log in to Brightmetrics. To avoid storing your password in configuration files or scripts, you can provide a SHA256 hash of the password, base64 encoded. Here are native command-line methods for generating this:

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 directly by prefixing it with *pass. For example, if your password is abcd1234, you can provide it as *passabcd1234 or as the encoded value 6c7nGrky/ehjM40Ivk3p3+OeoEm9r7NCzmWexUULaa4=.

Examples:

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

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

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

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

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

For applications that do not support Bearer token authentication (such as Power BI), you can use Basic authentication with the special username apikey and the API key as the password.

Requesting data

If you use a data access tool like Power BI or Tableau that supports OData v4, requesting data will be handled internally and you will not need to know the details below. If you are composing requests yourself using another tool or script, see the following sections.

Listing available data views

Each saved report 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, or discover available reports programmatically by requesting the OData Service Document:

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 matches what you see in the Brightmetrics reporting interface. The url is the URL relative to the OData root from which the report data can be requested. The name is a combination of both, formatted per OData specification requirements.

Retrieving report data

Once you have the report URL, request its data as follows:

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

By default, data is returned in JSON format. To request a different format, provide the appropriate media type in the HTTP Accept header. For example, to get unformatted CSV:

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

Supported media types:

The format can also be requested via the $format URL parameter:

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

Supported $format values:

Filtering

If no filters are supplied, results will match what is presented in the Brightmetrics web interface when the report is run without changing any configured filters. However, you can supply alternate values for any unlocked filter configured on the report, the same way scheduled reports can provide unique per-schedule filter options.

Filters are provided in a query parameter named $filter. Refer to the OData protocol documentation for a complete reference.

For example, if Queue Name is a filter on the report, it can be specified as Queue_Name eq 'Customer Service' or Queue_Name in ('Customer Service', 'Sales'). Note that spaces in field names are replaced with underscores per OData identifier restrictions — but never more than one underscore. For example, Time - Call - Total becomes Time_Call_Total, not Time___Call___Total.

Supported filter operators:

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')

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

Filter property names can generally be determined from the filter labels on the report using the replacement rules described above. You can also send a request to a report-specific metadata endpoint to get the list of available filters:

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 Call_Date_Time is a DateTimeOffset value (specify in ISO8601 format like YYYY-MM-DDTHH:mm:ssZ), Media_Type is a string value, and so on.

Note that Agent_Name is listed multiple times — these correspond to filtering agent names by a "proxy" such as queue membership or skill. These are all still "Agent Name" filters and cannot be combined. For instance, a filter cannot be provided for both Agent_Name and Agent_Name_by_Skill.

Asynchronous export

Requesting a lot of data or a report covering a long time range can take longer than an HTTP client or web server allows. Asynchronous exports are supported using the OData v4 mechanism specified for this purpose.

By including the HTTP header Prefer: respond-async, the OData endpoint will return 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 both the Location header and the statusUrl property of the response body contain a URL for checking job status and retrieving results. Polling while the job is still in progress returns the same 202 Accepted result. Once complete, it will return 200 OK with the report data. The status URL remains valid for 1 hour.

Server-side paging

If data is requested in OData format for a detail report covering a long time range without asynchronous export, the query will be divided into smaller time ranges and a continuation token will be included with each result set. The client can follow this to request the next range 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:

{
    "@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

The default timezone is UTC. To specify a different timezone, append the following parameter to the generated report API URL (do not include the <>):

?timezone=<timezoneName>

Example:

?timezone=Eastern%20Standard%20Time

Resulting in a full URL like:

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

Ensure spaces are escaped as %20 as shown above.

Common timezone options:

To get your current timezone in the Windows command prompt:

tzutil /g

For a full list of timezone options:

tzutil /l

API limits

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

We understand there may be cases where reasonable use exceeds that limit. For that reason, a reset button is available under the My Account section:

We hope this helps with this feature — we're excited to bring it to our customers!

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