Request

Response

    Retrieve BIM 360 Assets Data

    This tutorial demonstrates how to fetch your complete set of BIM 360 Asset data and project settings. This can be for the entirety of your Asset data, or filtered to a subset of Asset data.

    This set will include the assets themselves, as well as all of the surrounding Asset project settings:

    • categories
    • status sets / Asset statuses
    • Asset custom attributes
    • Assignments of status sets and Asset custom attributes to categories

    Usage of pagination and batch-fetch endpoints are subject to rate limiting. For more details on Assets API rate limits, see the Assets Rate Limits.

    Pagination

    Most of the endpoints detailed below are paginated. Assets API uses cursor-based pagination, in which an opaque cursorState token is used to track the state of the pagination. Each paginated response will contain a results section, in which the relevant entities themselves will be returned, and a pagination section which will return the information needed to continue the pagination to fetch the full set of result entities. Pagination fields are described as follows -

    FieldDescription
    limit The maximum number of entities that MAY be returned for the pagination request in the results section. The results MAY contain less than the limit due to filtering or for other reasons. Can be passed into any pagination request to limit the number of results returned.
    offset The offset of the first entity returned in the results section. The offset is returned for reference, but cannot be passed in explicitly for pagination requests (the offset is computed automatically from the cursorState).
    cursorState An opaque token to identify the subsequent pagination results. Can be passed in to the subsequent request to continue pagination. If cursorState is missing from the response, you have reached the end of the pagination and all results have been returned. To restart pagination, simply omit the cursorState from the pagination request.
    nextUrl The URL for the next paginated request. Contains the cursorState and any additional filters that have been applied. The cursorState is returned independently as well to give the client more flexibility in how they wish to paginate through entities. If nextUrl is missing from the response, you have reached the end of the pagination and all results have been returned.
    totalResults Not returned for all pagination endpoints, but if present will provide the total number of entities that can be returned through the pagination.

    For more details about BIM 360 Assets API, see the Assets Field Guide.

    Before You Begin

    • Register an app, and select the Data Management and BIM 360 APIs.
    • Acquire a 3-legged OAuth token with data:read scope.
    • Verify that you have access to the relevant BIM 360 account, project, and folder.
    • Retrieve the relevant BIM 360 account and project ID. In this tutorial we will use the example project ID f6a1e3b5-abaa-4b01-b33a-5d55f36ba047, but you should replace that with the project ID you have retrieved for your project.

    Step 1: Fetch Assets

    To get the assets themselves, use the project ID (f6a1e3b5-abaa-4b01-b33a-5d55f36ba047) to call GET assets/v2/projects/:projectId/assets.

    You will want to ensure you set the query parameter includeCustomAttributes=true if you wish to include Asset custom attribute data in your fetch. If you want to include deleted assets, you can set the query parameter includeDeleted=true as well.

    If you want to fetch a more targeted set of assets, you can provide additional filters in your request. This could include filtering by category, status, a specific location or a location hierarchy, custom attribute value(s), or any combination thereof. A complete list of the filters available, and how they are used, can be found in the query parameter documentation for the asset pagination endpoint. Filters provided in the initial pagination request will automatically be added to the nextUrl field to continue the filtered pagination.

    If you want to include only assets that have changed since previously retrieving assets, you can use the query parameter filter filter[updatedAt]={previousFetchTime}...

    Request

    curl 'https://developer.api.autodesk.com/bim360/assets/v2/projects/f6a1e3b5-abaa-4b01-b33a-5d55f36ba047/assets?includeCustomAttributes=true' \
         -H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT'
    

    Response

    {
      "results": [
        {
          "id": "a36ff5f6-8d51-43b1-a3da-ed748a63eb5b",
          "version": 1,
          "createdAt": "2021-01-05T20:37:28.731Z",
          "createdBy": "KKD4J2WE984T",
          "updatedAt": "2021-01-05T20:37:28.731Z",
          "updatedBy": "KKD4J2WE984T",
          "isActive": true,
          "categoryId": "12",
          "locationId": "2b2656fa-d5ff-4a1f-b022-c3e803cadbd3",
          "companyId": "9fd5d33e-6a51-4edc-a647-ed737162f65d",
          "clientAssetId": "MVS-3D2",
          "statusId": "f92f1b17-d0ff-427d-ba6d-7326eaf497b0",
          "customAttributes": {
            "ca1": "110"
          }
        },
        {
          "id": "c319622f-3f05-4bb4-b717-afe02b4cd3c3",
          "version": 2,
          "createdAt": "2021-01-05T20:37:28.732Z",
          "createdBy": "KKD4J2WE984T",
          "updatedAt": "2021-01-05T20:37:28.732Z",
          "updatedBy": "KKD4J2WE984T",
          "isActive": true,
          "categoryId": "13",
          "locationId": "de780160-6aaf-4e99-b1c1-fc9f5cedbfa7",
          "companyId": "9fd5d33e-6a51-4edc-a647-ed737162f65d",
          "clientAssetId": "MVS-3D3",
          "statusId": "fbcedb87-decb-4a17-826f-948e8d2585a5",
          "customAttributes": {
            "ca1": "110",
            "ca2": true,
            "ca6": "1942-11-27"
          }
        },
        {
          "id": "d1625a1c-5bab-464f-816c-a6b79d5da4af",
          "version": 3,
          "createdAt": "2021-01-05T20:37:28.733Z",
          "createdBy": "KKD4J2WE984T",
          "updatedAt": "2021-01-05T20:37:28.733Z",
          "updatedBy": "KKD4J2WE984T",
          "isActive": true,
          "categoryId": "13",
          "locationId": "8704717d-20f3-4586-b741-86891d727479",
          "companyId": "9fd5d33e-6a51-4edc-a647-ed737162f65d",
          "clientAssetId": "MVS-3E1",
          "statusId": "fbcedb87-decb-4a17-826f-948e8d2585a5",
          "customAttributes": {
            "ca1": "220",
            "ca2": false,
            "ca6": "1970-09-18"
          }
        }
      ],
      "pagination": {
        "limit": 3,
        "offset": 0,
        "cursorState": "eyJsaW1pdCI6MjUsIm9mZnNldCI6MjV9",
        "nextUrl": "https://developer.api.autodesk.com/bim360/assets/v1/projects/f6a1e3b5-abaa-4b01-b33a-5d55f36ba047/assets?cursorState=eyJsaW1pdCI6MjUsIm9mZnNldCI6MjV9"
      }
    }
    
    Show More

    Step 2: Fetch Categories

    To get the categories, use the project ID (f6a1e3b5-abaa-4b01-b33a-5d55f36ba047) to call GET assets/v1/projects/:projectId/categories.

    If you want to include only active categories, you can set the query parameter filter[isActive]=true. Note that filtering to only active or inactive categories can result in the returned tree not being fully intact.

    If you want to include only categories that have changed since previously retrieving categories, you can use the query parameter filter filter[updatedAt]={previousFetchTime}...

    Request

    curl 'https://developer.api.autodesk.com/bim360/assets/v1/projects/f6a1e3b5-abaa-4b01-b33a-5d55f36ba047/categories' \
         -H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT'
    

    Response

    {
      "results": [
        {
          "id": "10",
          "name": "ROOT",
          "description": "Auto-generated ROOT category for Assets Category Hierarchy",
          "createdAt": "2021-01-05T19:55:59.603Z",
          "createdBy": "assets-service",
          "updatedAt": "2021-01-05T19:55:59.603Z",
          "updatedBy": "assets-service",
          "subcategoryIds": [ "12" ],
          "isActive": true,
          "isRoot": true,
          "isLeaf": false
        },
        {
          "id": "12",
          "name": "Electrical",
          "parentId": "10",
          "createdAt": "2021-01-05T20:37:27.381Z",
          "createdBy": "KKD4J2WE984T",
          "updatedAt": "2021-01-05T20:37:27.381Z",
          "updatedBy": "KKD4J2WE984T",
          "subcategoryIds": [ "13" ],
          "isActive": true,
          "isRoot": false,
          "isLeaf": false
        },
        {
          "id": "13",
          "name": "Light Fixtures",
          "parentId": "12",
          "createdAt": "2021-01-05T20:37:27.648Z",
          "createdBy": "KKD4J2WE984T",
          "updatedAt": "2021-01-05T20:37:27.648Z",
          "updatedBy": "KKD4J2WE984T",
          "subcategoryIds": [ ],
          "isActive": true,
          "isRoot": false,
          "isLeaf": false
        },
      ],
      "pagination": {
        "totalResults": 3
      }
    }
    
    Show More

    Step 3: Fetch Status Sets And Asset Statuses

    To get the status sets, use the project ID (f6a1e3b5-abaa-4b01-b33a-5d55f36ba047) to call GET assets/v1/projects/:projectId/status-step-sets.

    If you want to include deactivated status sets and Asset statuses, you can set the query parameter includeDeleted=true.

    Note: If you just want to fetch the Asset statuses directly, you can call GET assets/v1/projects/:projectId/asset-statuses, but all statuses will be returned nested by fetching the full set of status sets as well.

    If you want to include only status sets that have changed since previously retrieving status sets, you can use the query parameter filter filter[updatedAt]={previousFetchTime}... Note that this will only reflect updates to the status sets themselves, not any of the contained statuses. To fetch Asset statuses that have been changed since a given time, you can call GET assets/v1/projects/:projectId/asset-statuses with filter[updatedAt]={previousFetchTime}...

    Request

    curl 'https://developer.api.autodesk.com/bim360/assets/v1/projects/f6a1e3b5-abaa-4b01-b33a-5d55f36ba047/status-step-sets' \
         -H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT'
    

    Response

    {
      "results": [
        {
          "id": "391e0d38-7ad2-41be-a87c-ca590f1fee91",
          "version": 2925,
          "projectId": "f6a1e3b5-abaa-4b01-b33a-5d55f36ba047",
          "name": "Default",
          "isDefault": true,
          "values": [
            {
              "id": "f92f1b17-d0ff-427d-ba6d-7326eaf497b0",
              "version": 11695,
              "description": "Specified",
              "bucket": "specified",
              "label": "Specified",
              "color": "blue",
              "projectId": "f6a1e3b5-abaa-4b01-b33a-5d55f36ba047",
              "statusStepSetId": "391e0d38-7ad2-41be-a87c-ca590f1fee91",
              "createdBy": "KKD4J2WE984T",
              "createdAt": "2020-02-26T18:58:40.163Z",
              "updatedBy": "KKD4J2WE984T",
              "updatedAt": "2020-02-26T18:58:40.163Z",
              "isActive": true
            },
            {
              "id": "ebac8429-1fa7-4d37-81c3-e3352f6a24ec",
              "version": 11693,
              "description": "Ordered",
              "bucket": "ordered",
              "label": "Ordered",
              "color": "yellow",
              "projectId": "f6a1e3b5-abaa-4b01-b33a-5d55f36ba047",
              "statusStepSetId": "391e0d38-7ad2-41be-a87c-ca590f1fee91",
              "createdBy": "KKD4J2WE984T",
              "createdAt": "2020-02-26T18:58:40.176Z",
              "updatedBy": "KKD4J2WE984T",
              "updatedAt": "2020-02-26T18:58:40.176Z",
              "isActive": true
            }
          ],
          "createdAt": "2020-02-26T18:58:40.130Z",
          "createdBy": "KKD4J2WE984T",
          "updatedAt": "2020-02-26T18:58:40.130Z",
          "updatedBy": "KKD4J2WE984T",
          "isActive": true
        },
        {
          "id": "f0fc7dc2-a325-4b1b-982b-584278f9a873",
          "version": 2926,
          "projectId": "f6a1e3b5-abaa-4b01-b33a-5d55f36ba047",
          "name": "Light Fixtures Statuses",
          "isDefault": false,
          "values": [
            {
              "id": "fbcedb87-decb-4a17-826f-948e8d2585a5",
              "version": 11694,
              "description": "Delivered",
              "bucket": "delivered",
              "label": "Delivered",
              "color": "red",
              "projectId": "f6a1e3b5-abaa-4b01-b33a-5d55f36ba047",
              "statusStepSetId": "f0fc7dc2-a325-4b1b-982b-584278f9a873",
              "createdBy": "KKD4J2WE984T",
              "createdAt": "2020-02-26T18:58:40.189Z",
              "updatedBy": "KKD4J2WE984T",
              "updatedAt": "2020-02-26T18:58:40.189Z",
              "isActive": true
            }
          ],
          "createdAt": "2020-02-26T18:58:40.130Z",
          "createdBy": "KKD4J2WE984T",
          "updatedAt": "2020-02-26T18:58:40.130Z",
          "updatedBy": "KKD4J2WE984T",
          "isActive": true
        }
      ],
      "pagination": {
        "limit": 3,
        "offset": 0
      }
    }
    
    Show More

    Step 4: Fetch Status Set to Category Assignments

    To get the status set to category assignments, use the project ID (f6a1e3b5-abaa-4b01-b33a-5d55f36ba047) and category IDs obtained in Step 3 to call POST assets/v1/projects/:projectId/category-status-step-sets/status-step-sets:batch-get.

    By default this will only return the status sets explicitly assigned to the given categories. If you wish to return each category’s effective status set assignment (taking inheritance into account), you can set the query parameter includeInherited=true.

    Request

    curl 'https://developer.api.autodesk.com/bim360/assets/v1/projects/f6a1e3b5-abaa-4b01-b33a-5d55f36ba047/category-status-step-sets/status-step-sets:batch-get?includeInherited=true' \
         -X 'POST' \
         -H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT' \
         -H 'Content-Type: application/json' \
         -d '{
               "ids": [
                 "10",
                 "12",
                 "13",
               ]
             }'
    
    Show More

    Response

    {
      "results": [
        {
          "categoryId": "10",
          "statusStepSetId": "391e0d38-7ad2-41be-a87c-ca590f1fee91"
        },
        {
          "categoryId": "12",
          "statusStepSetId": "391e0d38-7ad2-41be-a87c-ca590f1fee91"
        },
        {
          "categoryId": "13",
          "statusStepSetId": "f0fc7dc2-a325-4b1b-982b-584278f9a873"
        }
      ]
    }
    
    Show More

    Step 5: Fetch Asset Custom Attributes

    To get the Asset custom attributes, use the project ID (f6a1e3b5-abaa-4b01-b33a-5d55f36ba047) to call GET assets/v1/projects/:projectId/custom-attributes.

    If you want to include deactivated custom attributes, you can set the query parameter includeDeleted=true.

    If you want to include only custom attributes that have changed since previously retrieving custom attributes, you can use the query parameter filter filter[updatedAt]={previousFetchTime}...

    Request

    curl 'https://developer.api.autodesk.com/bim360/assets/v1/projects/f6a1e3b5-abaa-4b01-b33a-5d55f36ba047/custom-attributes' \
         -H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT'
    

    Response

    {
      "results": [
        {
          "id": "5903f625-9cb3-4c78-be51-468ec9073d2a",
          "version": 7485,
          "projectId": "f6a1e3b5-abaa-4b01-b33a-5d55f36ba047",
          "dataType": "numeric",
          "displayName": "Voltage",
          "name": "ca1",
          "description": "Voltage of the Electrical asset",
          "requiredOnIngress": true,
          "createdBy": "KKD4J2WE984T",
          "createdAt": "2020-03-22T23:09:03.730Z",
          "updatedBy": "KKD4J2WE984T",
          "updatedAt": "2020-12-18T22:16:44.083Z",
          "isActive": true
        },
        {
          "id": "e37911e0-1cc3-4f18-aa91-1ff1907e29d0",
          "version": 7486,
          "projectId": "f6a1e3b5-abaa-4b01-b33a-5d55f36ba047",
          "dataType": "boolean",
          "displayName": "Grounded",
          "name": "ca2",
          "description": "Is the Electrical asset grounded?",
          "requiredOnIngress": true,
          "createdBy": "KKD4J2WE984T",
          "createdAt": "2020-03-22T23:11:08.689Z",
          "updatedBy": "KKD4J2WE984T",
          "updatedAt": "2020-12-18T22:16:46.565Z",
          "isActive": true
        },
        {
          "id": "da5989c5-cdf5-40a3-8447-3168335637b5",
          "version": 5985,
          "projectId": "f6a1e3b5-abaa-4b01-b33a-5d55f36ba047",
          "dataType": "date",
          "displayName": "Install date",
          "name": "ca6",
          "requiredOnIngress": false,
          "createdBy": "KKD4J2WE984T",
          "createdAt": "2020-10-22T20:45:01.425Z",
          "updatedBy": "KKD4J2WE984T",
          "updatedAt": "2020-10-22T20:45:01.425Z",
          "isActive": true
        },
      ],
      "pagination": {
        "limit": 3,
        "offset": 0
      }
    }
    
    Show More

    Step 6: Fetch Category to Asset Custom Attribute Assignments

    To get the Asset custom attributes assigned to a category, use the project ID (f6a1e3b5-abaa-4b01-b33a-5d55f36ba047) and category IDs obtained in Step 3 to call GET assets/v1/projects/:projectId/categories/:categoryId/custom-attributes.

    A batch endpoint doe not yet exist for this call, so at this time a call must be made for each category ID individually to get the full set of assignments.

    By default this will only return the custom attributes explicitly assigned to the given category. If you wish to return the full set of custom attributes assigned to the given category, you can set the query parameter includeInherited=true. When includeInherited=true is set, an additional field will be included in the response for each returned custom attribute inheritedFromCategoryId which will indicate from which explicit category assignment the custom attribute is inherited from.

    Request

    curl 'https://developer.api.autodesk.com/bim360/assets/v1/projects/f6a1e3b5-abaa-4b01-b33a-5d55f36ba047/categories/13/custom-attributes?includeInherited=true' \
         -H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT'
    

    Response

    {
      "results": [
        {
          "id": "5903f625-9cb3-4c78-be51-468ec9073d2a",
          "version": 7485,
          "projectId": "f6a1e3b5-abaa-4b01-b33a-5d55f36ba047",
          "dataType": "numeric",
          "displayName": "Voltage",
          "name": "ca1",
          "description": "Voltage of the Electrical asset",
          "requiredOnIngress": true,
          "createdBy": "KKD4J2WE984T",
          "createdAt": "2020-03-22T23:09:03.730Z",
          "updatedBy": "KKD4J2WE984T",
          "updatedAt": "2020-12-18T22:16:44.083Z",
          "isActive": true,
          "inheritedFromCategoryId": "10"
        },
        {
          "id": "e37911e0-1cc3-4f18-aa91-1ff1907e29d0",
          "version": 7486,
          "projectId": "f6a1e3b5-abaa-4b01-b33a-5d55f36ba047",
          "dataType": "boolean",
          "displayName": "Grounded",
          "name": "ca2",
          "description": "Is the Electrical asset grounded?",
          "requiredOnIngress": true,
          "createdBy": "KKD4J2WE984T",
          "createdAt": "2020-03-22T23:11:08.689Z",
          "updatedBy": "KKD4J2WE984T",
          "updatedAt": "2020-12-18T22:16:46.565Z",
          "isActive": true,
          "inheritedFromCategoryId": "13"
        },
        {
          "id": "da5989c5-cdf5-40a3-8447-3168335637b5",
          "version": 5985,
          "projectId": "f6a1e3b5-abaa-4b01-b33a-5d55f36ba047",
          "dataType": "date",
          "displayName": "Install date",
          "name": "ca6",
          "requiredOnIngress": false,
          "createdBy": "KKD4J2WE984T",
          "createdAt": "2020-10-22T20:45:01.425Z",
          "updatedBy": "KKD4J2WE984T",
          "updatedAt": "2020-10-22T20:45:01.425Z",
          "isActive": true,
          "inheritedFromCategoryId": "13"
        },
      ],
      "pagination": {
        "limit": 3,
        "offset": 0,
        "totalResults": 3
      }
    }
    
    Show More

    Step 7: Fetch Locations

    The Locations API can be used to fetch location data for the locationId field on an asset via the GET Nodes endpoint.

    In order to use the Locations API, you will need to look up your locations container ID. More details on how to do this can be found in the Retrieve a Locations Container ID tutorial. For this example, we will assume the locations container ID we retrieved is 73807878-39c0-42f1-a8f9-29b3d3eb1c5f.

    For BIM360 projects, the tree ID will always be default.

    Request

    curl -v 'https://developer.api.autodesk.com/bim360/locations/v2/containers/73807878-39c0-42f1-a8f9-29b3d3eb1c5f/trees/default/nodes'
      -H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT'
    

    Response

    {
        "results": [
          {
            "id": "2b2656fa-d5ff-4a1f-b022-c3e803cadbd3,
            "parentId": null,
            "type": "Root",
            "name": "Project",
            "description": "Project description",
            "order": 0,
            "documentCount": 0,
            "areaDefined": false
          },
          {
            "id": "de780160-6aaf-4e99-b1c1-fc9f5cedbfa7,
            "parentId": "2b2656fa-d5ff-4a1f-b022-c3e803cadbd3",
            "type": "Area",
            "name": "Area 1",
            "description": "An Area 1 node",
            "order": 0,
            "documentCount": 2,
            "areaDefined": true
          }
        ],
        "pagination": {
          "limit": 2,
          "offset": 0,
          "totalResults": 2,
          "nextUrl": "/locations/v2/containers/73807878-39c0-42f1-a8f9-29b3d3eb1c5f/trees/default/nodes?limit=2&offset=2"
        }
      }
    
    Show More

    Step 8: Fetch Asset Relationships

    Assets can be associated with other entities such as Issues, Checklists, Documents, etc. You can use the Relationship API to search for all relationships associated with your project, or for a given Asset directly.

    For the Relationship API, your Container ID will simply be your Project ID.

    See the Relationship v2 APIs documentation.

    You can search for all relationships in your project which include an “asset” type using the following query parameters:

    Query ParameterValue(s)
    domain The Assets Relationship domain: autodesk-bim360-asset
    type The Assets Relationship types (see below for available options)
    id OPTIONAL - ID of the Asset to search relationships for
    withDomain OPTIONAL - The related entity domain (see below for available options)
    withType OPTIONAL - The related entity type (see below for available options)
    withId OPTIONAL - The related entity ID. e.g. checklist ID, issue ID, checklist template ID

    Request

    curl -v 'https://developer.api.autodesk.com/bim360/relationship/v2/containers/f6a1e3b5-abaa-4b01-b33a-5d55f36ba047/relationships:search?domain=autodesk-bim360-asset&type=asset' \
      -H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT'
    

    Response

    {
      "page": {
        "continuationToken": "10",
        "syncToken": "eyAibGFzdENoZWNrZWQiOiIyMDE5LTEwLTE4VDEyOjEwOjA3Ljc5NloiIH0="
      },
      "relationships": [
        {
          "id": "e005c68b-53af-41d0-9e56-9be86cd9c5a9",
          "createdOn": "2020-07-28T19:52:44.262208+00:00",
          "isReadOnly": true,
          "isService": true,
          "isDeleted": false,
          "entities": [
            {
              "createdOn": "2020-07-28T19:52:44.198281+00:00",
              "domain": "autodesk-bim360-asset",
              "type": "asset",
              "id": "71fa0b41-cd23-4439-8def-4348a2a45d4b"
            },
            {
              "createdOn": "2020-07-28T19:52:44.198281+00:00",
              "domain": "autodesk-bim360-issue",
              "type": "issue",
              "id": "84929da1-f71c-4a4d-9535-32c23db9a378"
            }
          ]
        }
      ]
    }
    
    Show More

    For more information on querying the Relationship API, see the Relationship Querying Tutorial.

    Once you have the entities and their relationships to the given assets you can use the relevant APIs to fetch the data for the given entities. This may require setting up access to other APIs, depending on what type of entities are linked to your Assets. See Retrieve Issues and Get Checklist Template Endpoint for examples of retrieving related entities.