Query Usage Information
Before You Begin
Make sure that you have registered an app. and successfully acquired an OAuth token with the data:read
scope.
Step 1: Obtaining an Access Token
All calls to the Token Flex Usage Data API must be authenticated and a valid access token is required for each API call. Please refer to this how-to guide on how an access token can be obtained.
Step 2: Submit Query
The Token Flex Usage Data API exposes a POST usage/:contract_number/query endpoint that allows for the submission of queries. Queries are processed asynchronously. This endpoint returns a query ID, which is then used with the GET usage/query/:query_id endpoint to check the query status and retrieve the results.
Example Request
CONTRACT_NUMBER = "12345"
curl -H "Content-Type: application/json" -H "Authorization: Bearer hW0DvSvGgszPis1Yhot4c8kWW3NG" -X POST -H 'Content-Type: application/json'
https://developer.api.autodesk.com/tokenflex/v1/usage/${CONTRACT_NUMBER}/query
-d '
{
"fields": [
"usageCategory",
"productName"
],
"metrics": [
"tokensConsumed"
],
"where": "contractYear=1 AND productName IN ('Revit Live', 'Vault Office', 'Moldflow Adviser Ultimate', 'ReMake')"
}
'
Note that line breaks have been added to the cURL command above for ease of reading. Make sure to remove them before executing any code in your terminal.
If successful, the response body looks like:
{
"status": "QUEUED",
"id": "query:dd8a8fa076a3a82cb994eb9689392d31d6ee18c7222fd7035efffe51",
"detail_uri": "/v1/usage/12345/query/query:dd8a8fa076a3a82cb994eb9689392d31d6ee18c7222fd7035efffe51"
}
The response contains a detail_uri
field, which is vital information to be used for the next steps.
Step 3: Poll for Query Results
Using the detail_url
value returned in Step 2, poll the GET usage/:contract_number/query/:query_id
endpoint to check the status of the query. A status of “FAILED” or “TIMEOUT” indicates that the query failed due to an error; “EXPIRED” indicates that the query results
are no longer available. Use the offset
and limit
query parameters to paginate through the query results; by default the first 100 results will be returned.
If successful, the response body looks like:
{
"status": "DONE",
"result": {
"columns": [
"usageCategory",
"productName",
"tokensConsumed"
],
"rows": [
[
"PRODUCT_CONSUMPTION",
"Moldflow Adviser Ultimate",
60.0
],
[
"PRODUCT_CONSUMPTION",
"ReMake",
46.0
],
[
"PRODUCT_CONSUMPTION",
"Revit Live",
128.0
],
[
"PRODUCT_CONSUMPTION",
"Vault Office",
3.0
]
],
"total": 4,
"offset": 0,
"limit": 100,
}
}
Within the result
element, the columns
array identifies the columns in the query result and the rows
array identifies the values in each row/column.
For the example above, the value of the productName
column in the second row is Remake
.
(Optional) Step 4: Get the results as a CSV file
Sometimes, you want to acquire the output of the query as a CSV file for ingestion into another system. You may be required to do this if your query fetches a lot of data and exceeds the 5-minute time limit. In those cases, use the Export API.
Continue to the Export walkthrough.