Request

Response

    POST

    /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.
    * Required

    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 the where 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 but b% 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"
          }'
    
    Show More

    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"
          }'
    
    Show More

    Response

    {
      "title": "NoSupportedProductsError",
      "detail": "NoSupportedProductsError: No supported products"
    }
    

    Example

    Forbidden. Not a Business Success Plan 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"
    }