Exporting Using Brightmetrics API

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:

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 Brightmetrics user interface, here on your saved report:


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



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


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


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


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.

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.

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:

Format Media type
CSV (unformatted) text/csv or text/csv; unformatted
CSV (formatted) text/csv; formatted
PDF (portrait) application/pdf or application/pdf; portrait
PDF (landscape) application/pdf; landscape
Excel (xlsx)


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:

Format $format
CSV (unformatted) csv or csv;unformatted
CSV (formatted) csv;formatted
PDF (portrait) pdf or pdf;portrait
PDF (landscape) pdf;landscape
Excel (xlsx)


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:

Operator Meaning Example
eq Equal To $filter=Queue_Name eq 'Customer Service'
in In list of values $filter=Queue_Name in ('Customer Service', 'Sales')
gt Greater Than $filter=Time_Call_Total gt 10
ge Greater Than or Equal To $filter=Call_Date_Time ge 2020-06-01T00:00:00Z
lt Less Than $filter=Time_Abandon_Total lt 20
le Less Than or Equal To $filter=Call_Date_Time le 2020-07-01T00:00:00Z
ne Not Equal To $filter=Agent_Name ne 'Agent Spare 1

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">
        <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" />
            <EntityContainer Name="Saved Reports">
                <EntitySet Name="Agent_Detail_6f40b845fb284547b73be11ce29f481b_filters" EntityType="Brightmetrics.filters_6f40b845-fb28-4547-b73b-e11ce29f481b" />

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.


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.


Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request



Article is closed for comments.