Query API
The Query API is a powerful analytics API that harnesses GraphQL to give you access to Medallia Experience Cloud data through a single endpoint. Send a standard HTTP POST request to the server through a single endpoint, specify what data you need, and get back exactly that.
Experience Cloud generates valuable information and, although it has its own robust analytics engine, and integrated collecting and reporting capabilities, sometimes it is necessary to retrieve and manipulate experience data.
The Query API is an API that applications can use to pull Experience Cloud record-level data into your BI tool, data warehouse or data visualization app to create tailored insights for stakeholders, or pull aggregated data for ad-hoc analysis, to identify improvement opportunities in your business.
The Experience Cloud security framework uses OAuth 2.0 for authenticating access to data. Applications that access the Medallia Experience Cloud APIs are OAuth clients. That means all Query API requests require an OAuth access token. For details about getting a token, see Authentication and authorization.
Usage
The Query API is the primary way for apps to access Experience Cloud raw survey data. All of our analytics tools interact with the Query API in some way, especially our Report modules.
The API is a GraphQL interface. GraphQL is a standard and well known language, ideal for querying interactive data. Moreover, the API is self-documented through it's schema, since GraphQL supports introspection. Developers can explore the graph in an interactive way using any GraphQL IDE (such as Altair GraphQL Client, GraphiQL, Insomnia, and Postman).
Use Query API to:
Fetch record-level data (for invitations, feedback, and customer experience profiles).
Filter the data using complex filters.
Filter using standard logical and comparison operators.
Filter by date range.
Filter by segment.
Filter by field and unit field value.
Sort data by a field.
Pull an incremental data set.
Pull a paginated data set.
Aggregate record-level data using simple aggregations: AVG, SUM and Count.
User single number aggregation — it returns a number given a field.
Use 2D table aggregation — each cell in the table aggregates the data given the row and column.
Query R-fields.
Fetch field metadata.
Filter metadata by type or name.
See Data queries and Metadata queries for more details.
Authentication and authorization
Authentication identifies who is making an API request, and authorization identifies what data the requester may access. OAuth is an industry standard for authorizing limited access to services and data. Applications must obtain a secure token that identifies the application that makes the request. The token is passed to the resource server (API server) with each API request. For more information, see Authenticating APIs with OAuth.
To use the Query API:
The application must have an account
The account's role must have permission to access the API. .
API access is authenticated with OAuth. To use OAuth, the application must first obtain an OAuth access token, by requesting one for the application's client ID and secret. .
Request/response formats
Requests sent to Experience Cloud Query API are generally HTTP POST protocol. The information in the request includes:
A required
Bearer
header type field with the access token.The request URL:
Always use the base instance for the company's Medallia installation; do not try to bypass the API gateway.
URL and endpoint
The Query API accesses resources from a URL that follows this format:
https://<api-host>/<resource-group>/<resource-group-version>/<endpoint>
api-host is the server for your company's Medallia Experience Cloud instance.
resource-group is
data
.resource-group-version is
v0
.endpoint is
query
.
For example, if that URL is:
https://instance.medallia.com/company
Environment | API URL |
---|---|
Production (company and instance names are the same) | https://<instance>.apis.medallia.com/data/v0/query |
Production (company and instance names are different) | https://<instance>-<company>.apis.medallia.com/data/v0/query |
Sandbox | https://<sandbox-name>-<company>.apis.sbx.<data-center>.medallia.com/data/v0/query |
POST body
Instead of using several requests to different endpoints, with GraphQL, you can send a single HTTP POST request with detailed information about your data needs in the form of a query in the body of the request.
The queries are done with this basic JSON structure:
Where:
Filtering to apply to the request.
filter
identifies the records to retrieve. See Filtering and sorting data for details.
Pagination limits the count of elements (records) returned, and their relationship to the previous query. See Pagination for details.
after
is a cursor that identifies where to start the page. For the initial query, the value isnull
, but for subsequent queries, it is the last record at the end of the previous page, as identified by theendCursor
value.first
is the page size: return up to this many results.
Pagination info used in the next "paged" query. See Pagination for details.
endCursor
is the last result in the page, and is the value to use as theafter
in the next page.hasNextPage
is true when there are more records after the current page.
Total count of records returned.
totalCount
is the number of records that match the filter criteria.
Data requested.
nodes
is the container for the requested data, and defines the record data to return.dataTable
allows formatting the response as a table to optimize the response for better data consumption.
GET requests
While the most common use of the API is done through HTTP POST requests, the Query API supports HTTP GET query requests. When calling the API with GET, pass each attribute as a JSON-encoded string in a query parameter:
GET /data/v0/query?query="<GRAPHQL QUERY>"&variables="{}"&operationName="queryName"
Response
Regardless of the request method, the response is a JSON object in this format:
{
"data": { },
"errors": null,
"_links": null,
"_allowed": [
"POST",
"GET"
]
}
Where data
and errors
are the two important attributes.
Element | Description | Type | Notes |
---|---|---|---|
data | Container for the requested data. | Data object | |
errors | Brief description of the error that occurred. | String | |
_allowed | Allowed HTTP requests. | String | Values:
|
If you are unfamiliar with Query API, we recommend that you start with these documents:
If you want to dive right in and begin using the API, follow the steps in Quickstart: Query API.