Retrieves a list of iTwins that the calling user is a member of.
Max Return
Some users can be members of a very large number of iTwins. The iTwins API uses the X-Max-Return header to limit the number of iTwins returned from any query.
X-Max-Return
- Default Behavior: If not specified, the maximum number of iTwins returned will default to 1000. For example, if a user has access to 40,000 iTwins, only up to 1000 iTwins can be paged through. Attempting to page past 1000 will not result in an error; it will simply stop returning iTwins.
- Customizing the Limit: You can set X-Max-Return to any number between 1 and 10,000. Setting a lower value can improve query performance. For instance, if your application displays no more than 500 iTwins, set X-Max-Return to 500.
- Response Header: The value of X-Max-Return used in the query is also returned in a response header with the same name.
If you need to get more than 10000 iTwins, use the iTwin Exports API. There is no limit to the number of iTwins that can be exported.
OData Queries
We have added support for advanced odata queries. For simple queries, you can still use the other query parameters (status, type, number, displayName, parentId, iTwinAccountId and $search). The odata $filter allows you to build more advanced queries. You cannot use the advanced odata $filter and the simple query parameters (other than subClass) at the same time.
Example: Find Asset or Project iTwins created since September 1, 2024 that have 'abc' in the displayName. Select only the id, displayName and createdDateTime. Order them by displayName.
/itwins?subClass=Asset,Project&$filter=createdDateTime+ge+2024-09-01T00:00:00Z+and+contains('abc',displayName)&$select=id,displayName,createdDateTime&$orderby=displayName
There are more examples in the parameter definition below.
Inactive iTwins
iTwins with status=Inactive are not returned by default. This improves query performance and reduces clutter in user interfaces by filtering out unused iTwins. You should still provide a way for users to see their Inactive iTwins if they request them. In the API, you can do this by setting the status parameter or by using the includeInactive parameter.
If status=Inactive, the API will return only Inactive iTwins.
If includeInactive=true, the API will return all iTwins (Active, Trial and Inactive).
The includeInactive parameter is optional and defaults to false. A 422 error will be returned if you try to use a status parameter at the same time as the includeInactive parameter.
Authentication
Requires Authorization
header with valid Bearer token for scope itwin-platform
.
For more documentation on authorization and how to get access token visit OAUTH2 Authorization page.
Authorization
Any user can call this endpoint. It will only return iTwins that the user is a member of. Use the Access Control API to manage an iTwin's members.