iTwin Projects icon

iTwin Projects

Comprehensive iTwin Projects API

Actions26

Overview

This node operation "Get my iTwins" allows users to query and retrieve a list of iTwins (digital twins) that the authenticated user has access to. It supports filtering, searching, and sorting of iTwins based on various criteria such as subclass, status, type, display name, parent ID, ownership, and more.

Typical use cases include:

  • Fetching all iTwins a user is a member of or owns.
  • Searching for specific iTwins by number or display name.
  • Filtering iTwins by status or type.
  • Retrieving iTwins belonging to an organization (for admins).
  • Limiting the returned properties to optimize performance.

Practical examples:

  • A project manager wants to list all active iTwins related to assets and projects they are involved in.
  • An admin wants to get all iTwins under their organization.
  • A user searches for iTwins containing a certain keyword in their display name or number.

Properties

Name Meaning
Sub Class Specify one or more subclasses (comma-separated) to filter the query. Queries will be faster if specified. Example: Asset,Project to find all Assets or Projects matching the criteria.
Status Filter iTwins by a particular status. Cannot be used together with Include Inactive.
Type Filter iTwins by a particular type.
Number Find iTwins with the exact number specified. Cannot be used together with the Search parameter.
Display Name Find iTwins with the exact display name specified. Cannot be used together with the Search parameter.
Parent ID Find iTwins that are children of the specified parent ID.
iTwin Account ID Find iTwins owned by the specified iTwin account ID.
Search Search string to find iTwins where the string appears anywhere in the number or display name. Cannot be used together with Number or Display Name parameters.
Select Comma-delimited list of iTwin properties to return. Keeping this list small improves query performance and reduces data size. If specified, it overrides the default minimal representation.
Filter OData filter expression to further limit query results. Text values are case insensitive. Example: parentId eq '78202ffd-272b-4207-a7ad-7d2b1af5dafc' and (startswith('ABC',number) or startswith('ABC',displayName))
Orderby Used to order the results. Example: displayName ASC
Include Inactive Boolean flag to include inactive iTwins in the results. Defaults to false. Cannot be used together with Status.
X Max Return Maximum number of iTwins to return from the query (between 1 and 10,000). Default is 1000. Controls total count across all pages, not page size. Lower values can improve performance.
X iTwin Query Scope Specifies the scope of the query:
- MemberOfiTwin (default): limits results to iTwins the user is a member of.
- OrganizationAdmin: limits results to iTwins belonging to the user's organization; requires admin privileges. Useful for organization-wide queries.

Output

The output is an array of JSON objects representing the iTwins matching the query criteria. Each item contains the properties of an iTwin as returned by the API, which may vary depending on the $select parameter or default minimal representation.

No binary data output is indicated.

Example output structure (simplified):

[
  {
    "id": "string",
    "number": "string",
    "displayName": "string",
    "status": "string",
    "type": "string",
    "parentId": "string",
    "iTwinAccountId": "string",
    ...
  }
]

Dependencies

  • Requires an API key credential or OAuth2 token configured in n8n for authenticating requests to the iTwin platform.
  • Uses Bentley's iTwin API endpoints to perform queries.
  • No additional external dependencies beyond standard HTTP request capabilities.

Troubleshooting

  • Conflicting Parameters: Using number or displayName together with search will cause errors. Ensure only one of these is set.
  • Invalid Filter Syntax: The $filter property must follow OData syntax. Incorrect filters will result in API errors.
  • Permission Issues: Using X iTwin Query Scope as OrganizationAdmin requires admin privileges; otherwise, the query will fail.
  • Max Return Limits: Setting X Max Return outside the allowed range (1-10,000) may cause errors or unexpected behavior.
  • Empty Results: If no iTwins match the criteria, the output will be empty. Verify filter and search parameters.
  • API Rate Limits: Excessive querying might hit API rate limits; consider adding delays or reducing query frequency.

Links and References

Discussion