Run ECSQL Query - iModel Query

iModel Query

Download API definition:

This operation is a Technical Preview and is available for testing purposes only. Do not use in production.

POST https://dev-api.bentley.com/imodel-query/itwins/{itwin}/imodels/{imodel}/changesets/{changeset}/queries

Executes an ECSQL query on the specified iModel changeset. This operation supports both synchronous and asynchronous query execution patterns.

Request

The request body must contain:

query - A valid ECSQL query string

Optional Parameters

The following parameters can be included in the request body:

args - Optional parameters object for parameterized queries
includeMetadata - Whether to include column metadata in the response
limit - Maximum number of rows to return per page
skip - Number of rows to skip (for pagination)

Important: When used in the POST request body, these parameters only apply to:

Synchronous responses (status 200)
The first page of results only

For asynchronous queries (status 201) or subsequent pages, use these parameters as query parameters in the GET request to retrieve query results.

Query Processing

Initial State: Query starts in Pending state
Execution: Progresses to Running state
Completion: Ends in either Completed or Failed state

Response Behavior

The API may respond with one of two patterns, and applications must be prepared to handle both:

Status 200: Query completed and results are included
- Contains full query results immediately
- Response format matches the GET operation for retrieving query results
- Honors includeMetadata, limit, and skip parameters from request body (first page only)
Status 201: Query accepted and processing
- Returns only the query ID and state
- Use the query ID with the GET operation to retrieve results when ready
- Parameters from request body (includeMetadata, limit, skip) are ignored
- Use query parameters in subsequent GET requests to control result formatting and pagination

Important: The response pattern is determined by the server and cannot be controlled by the client. Applications must handle both scenarios.

Data Retention

Query results are stored for 24 hours after completion, allowing time for result retrieval and pagination.

Request parameters

itwin

Yes

iTwin ID

imodel

Yes

iModel ID

changeset

Yes

changeset ID

Request headers

Authorization

Yes

OAuth access token with itwin-platform scope

Yes

Setting to application/vnd.bentley.itwin-platform.v1+json is recommended.

QueryRequestBody

query

String

Yes

args

QueryArguments

includeMetadata

Boolean

skip

Number

limit

Number

Example

json

{
    "query": "string",
    "args": {}
}

Response 200 OK

A response

json

{
    "id": "620b43a3-a30e-48d8-92a8-ab1eb0fd591d",
    "state": "Completed",
    "rows": [
        [
            "0x1",
            "0xcf",
            {
                "Id": "0x1",
                "RelECClassId": "0x40"
            },
            "2022-12-15T12:40:13.047Z",
            {
                "Id": "0x1f",
                "RelECClassId": "0x47"
            },
            {
                "Id": "0x1",
                "RelECClassId": "0x49"
            },
            "BayTown_Sample"
        ]
    ],
    "links": {
        "self": "http://api.bentley.com/imodel-query/itwins/1f947d72-9983-4e46-89c2-e9ed9a3d4fec/imodels/4276bd1d-959b-4078-83c3-501571409a97/changesets/6cee950fcdfa3f01df925c04ed10fae1bfb233e7/queries/620b43a3-a30e-48d8-92a8-ab1eb0fd591d"
    },
    "meta": [{
            "className": "",
            "name": "ECInstanceId",
            "typeName": "long",
            "accessString": "ECInstanceId",
            "extendedType": "Id"
        },
        {
            "className": "",
            "name": "ECClassId",
            "typeName": "long",
            "accessString": "ECClassId",
            "extendedType": "ClassId"
        },
        {
            "className": "BisCore:Element",
            "name": "Model",
            "typeName": "navigation",
            "accessString": "Model"
        },
        {
            "className": "BisCore:Element",
            "name": "LastMod",
            "typeName": "dateTime",
            "accessString": "LastMod"
        },
        {
            "className": "BisCore:Element",
            "name": "CodeSpec",
            "typeName": "navigation",
            "accessString": "CodeSpec"
        },
        {
            "className": "BisCore:Element",
            "name": "CodeScope",
            "typeName": "navigation",
            "accessString": "CodeScope"
        },
        {
            "className": "BisCore:Element",
            "name": "CodeValue",
            "typeName": "string",
            "accessString": "CodeValue"
        },
        {
            "className": "BisCore:Element",
            "name": "UserLabel",
            "typeName": "string",
            "accessString": "UserLabel"
        },
        {
            "className": "BisCore:Element",
            "name": "Parent",
            "typeName": "navigation",
            "accessString": "Parent"
        },
        {
            "className": "BisCore:Element",
            "name": "FederationGuid",
            "typeName": "binary",
            "accessString": "FederationGuid",
            "extendedType": "BeGuid"
        },
        {
            "className": "BisCore:Element",
            "name": "JsonProperties",
            "typeName": "string",
            "accessString": "JsonProperties",
            "extendedType": "Json"
        }
    ]
}

Response 201 Created

A response

json

{
    "id": "68cd2bc6-afd9-4fdf-a9af-129d7e4dd894",
    "state": "Pending"
}

This response indicates that request lacks valid authentication credentials. Access token might not been provided, issued by the wrong issuer, does not have required scopes or request headers were malformed.

json

{
    "error": {
        "code": "HeaderNotFound",
        "message": "Header Authorization was not found in the request. Access denied."
    }
}

Response 429 Too many requests

This response indicates that the client sent more requests than allowed by this API for the current tier of the client.

json

{
    "error": {
        "code": "RateLimitExceeded",
        "message": "The client sent more requests than allowed by this API for the current tier of the client."
    }
}

Response headers

retry-after

Number of seconds to wait until client is allowed to make more requests.

Definitions

QueryRequestBody

query

String

args

QueryArguments

includeMetadata

Boolean

skip

Number

limit

Number

json

{
    "additionalProperties": false,
    "properties": {
        "query": {
            "type": "string"
        },
        "args": {
            "$ref": "#/components/schemas/QueryArguments"
        },
        "includeMetadata": {
            "type": "boolean"
        },
        "skip": {
            "type": "number"
        },
        "limit": {
            "type": "number"
        }
    },
    "required": [
        "query"
    ]
}

QueryArguments

QueryResponse

QueryResponsePending state

Pending

String

json

{
    "enum": [
        "Pending"
    ],
    "type": "string",
    "title": "QueryResponsePending state"
}

QueryResponsePending

String

links.self

String

links.prev

String

links.next

String

QueryResponsePending state

QueryResponsePending-state

json

{
    "additionalProperties": false,
    "properties": {
        "id": {
            "type": "string"
        },
        "links": {
            "additionalProperties": false,
            "properties": {
                "self": {
                    "type": "string"
                },
                "prev": {
                    "type": "string"
                },
                "next": {
                    "type": "string"
                }
            }
        },
        "state": {
            "enum": [
                "Pending"
            ],
            "type": "string",
            "title": "QueryResponsePending state",
            "$ref": "#/components/schemas/QueryResponsePending-state"
        }
    },
    "required": [
        "id",
        "state"
    ]
}

Error

Contains error information.

code

String

One of a server-defined set of error codes.

message

String

A human-readable representation of the error.

target

String, null

The target of the error.

json

{
    "type": "object",
    "description": "Contains error information.",
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        },
        "target": {
            "type": "string",
            "description": "The target of the error.",
            "nullable": true
        }
    },
    "required": [
        "code",
        "message"
    ],
    "additionalProperties": true
}

Error Response

Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.

error

Error

Error information.

json

{
    "type": "object",
    "title": "Error Response",
    "description": "Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.",
    "properties": {
        "error": {
            "description": "Error information.",
            "$ref": "#/components/schemas/Error"
        }
    },
    "required": [
        "error"
    ],
    "additionalProperties": false
}

Was this page helpful?

Request

Optional Parameters

Query Processing

Response Behavior

Data Retention

Request

Request parameters

Request headers

Request body

QueryRequestBody

Example

Response

Response 200 OK

Response 201 Created

Response 401 Unauthorized

Response 429 Too many requests

Response headers

Definitions

QueryRequestBody

QueryArguments

QueryResponse

QueryResponsePending state

QueryResponsePending

Error

Error Response