/usage-queries
Run a custom query on the usage data.
Resource Information
Method and URI | POST https://developer.api.autodesk.com/insights/v1/usage-queries |
Required OAuth Scopes | data:write |
Data Format | JSON |
Request
Headers
Authorization* string | Must be Bearer <token> , where <token> is obtained via a three-legged OAuth flow. |
Request
URI Parameters
limit integer | For paging through results, this is the number of results that will be returned. Defaults to 100. |
offset integer | For paging through results, this is the first result that will be returned. Defaults to 0. |
contextId string | Limits the results to the specified context. |
Request
Body Structure
The body of the request is a JSON document describing the fields and metrics to use in the query, as well as an optional where
clause providing criteria used to limit the
scope of the query. Queries must include either metrics or fields, or both metrics and fields.
See Fields and Metrics for all available Fields and Metrics.
The basic structure of the JSON document is as follows:
fields array of strings | List of fields to use in the query. |
metrics array of strings | List of metrics to use in the query. |
where string | SQL-style where clause which is used as a filter clause when retrieving data. |
orderBy string | SQL-style order by clause for sorting, i.e. ‘fullName ASC’ or ‘productName DESC’. |
contextId string | Limits the results to the specified context. |
Usage limitations
- The keyword
not
is not allowed in thewhere
clause. Use!=
for not equals. - Some Fields cannot be filtered on. Refer to Fields and Metrics for details.
- Nested conditions can be at most 1 deep.
- Wildcard values (
%
) must contain at least three non-wildcard characters (for example,bob%
is allowed butb%
is not). - Wildcard values are not allowed for the enum fields status, source.
Response
HTTP Status Code Summary
200 OK | Request succeeded. |
400 Bad Request | The API request was invalid/improper/etc. |
401 Unauthorized | The API request was not authenticated. |
Response
Body Structure (200)
pagination object | |
pagination.pagination[i].totalResults integer | Total number of records available. |
pagination.pagination[i].offset integer | Offset (from zero) representing the start of the current result set. |
pagination.pagination[i].limit integer | Number of results in the current result set. |
id string | Unique identifier for this query. |
status string | Status of the query.
Possible values: SUBMITTED , RUNNING , COMPLETED , EXPIRED , ERROR |
columns array of strings | Array of column names (which can be both Fields and/or Metrics) returned in the results. |
rows array of strings | The query results, in the same order as result.columns . |
columns and rows can be any values from Fields and Metrics.
Example
Successful requesting a query for unique number of users by product for team 4320984. (200)
Request
curl -X POST \
'https://developer.api.autodesk.com/insights/v1/usage-queries?offset=0&limit=100&contextId="4280140"' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1N' \
-d '{
"fields": ["productName"],
"metrics": ["uniqueUsers"],
"where": "",
"orderBy": "productName",
"contextId": "4320984"
}'
Response
{
"id": "8ff2510db9d1a2d4e9e35cedace73502127cde22e37417316565a5350704f4a2",
"status": "SUBMITTED",
"startTime": 1636577986
}
Example
Bad Request. Querying a team that has no active products. (400)
Request
curl -X POST \
'https://developer.api.autodesk.com/insights/v1/usage-queries?offset=0&limit=100&contextId="4320984"' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1N' \
-d '{
"fields": ["productName"],
"metrics": ["uniqueUsers"],
"where": "productLineCode=MAYALT",
"orderBy": "productName",
"contextId": "4320984"
}'
Response
{
"title": "NoSupportedProductsError",
"detail": "NoSupportedProductsError: No supported products"
}
Example
Forbidden. Not a premium admin. (403)
Request
curl -X POST \
'https://developer.api.autodesk.com/insights/v1/usage-queries?offset=0&limit=100&contextId="4320984"' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer eyJhbGciOiJUzI1N'
Response
{
"title": "ACCESS_DENIED",
"detail": "No further detail provided"
}