Get Exports - Mesh Export | iTwin Platform

Mesh Export

Download API definition:

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

GET https://api.bentley.com/mesh-export/[?iModelId][&changesetId][&$top][&$skip][&$orderBy][&cdn][&tileVersion][&exportType][&iTwinJS]

Retrieves a list of all 3D Tiles generation tasks, each with its current status (not started, in-progress, completed, or failed).

To obtain the URL for the tiles so that the 3D viewer can stream them, you can use the prefer header with the value return=representation. This will include a URL for the viewer to access the tiles.

When a mesh export succeeds, the _links.mesh returns a URL to stream the resulting tiles from the blob container.

You can list the contents of the container by appending the query parameters restype=container&comp=list to the URL.

The link is valid for one hour.

Streaming 3DTiles

Exporting 3DTiles always produces a JSON file tileset.json, that contains the description and structure of the tileset, and many 3D tile files in GLB format (GLTF binary).

3D viewers require a URL to the tileset.json file to start streaming the tiles.

To generate this URL you must:

Split the URL provided in _links.mesh.href in two parts: the URL base and the query parameters.
Append the file name tileset.jsonto the base URL.
Append the query parameters to the resulting previous URL.

For example: {baseUrl}/tileset.json?{SASKey}

Selecting the latest version

To obtain the latest version, you do not need to define the changesetId. This will return the list of exports ordered by changesetIndex, with the newest first.

To filter the exports, we recommend using &exportType=3DTiles. This will also help the system improve auto-generation, as it will allow the service to know the type of export we want to use.

Auto-generation

Recently, the iTwin platform incorporated the ability to auto-generate 3D Tiles when iModels change. Therefore, it is no longer necessary to manually generate the tiles, as the platform will handle it.

Sometimes, the generation of tiles may be starting. If the call to get-exports does not return any export, we recommend trying again after a few seconds (10s-30s).

Important: The first generation of 3D tiles for an iModel may be slower, but subsequent automatic generations will be faster, so we recommend keeping this in mind and informing the user.

SASKey

When accessing 3D Tiles, the provided URL includes a Shared Access Signature (SAS) key, which grants secure, temporary access to each file within the container. The SAS key is embedded in the URL, allowing direct access to the files without requiring further authentication. Ensure that the URL retains its SAS key, as it controls access permissions and is necessary to retrieve the files in the container.

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.

Request

Request parameters

iModelId

Optional iModel Id query parameter. Will return all exports contained in the iModel as long as user has access to it.

changesetId

Optional Changeset Id query parameter. Will return all exports that have the matching changeset Id.

$top

The $top system query option requests the number of items in the queried collection to be included in the result.

$skip

The $skip query option requests the number of items in the queried collection that are to be skipped and not included in the result.

$orderBy

The $orderBy query parameter allows you to order by exports' last modified date. At the moment, only $orderBy=date:asc and $orderBy=date:desc is supported.

cdn

Optional cdn query parameter. Will return cdn based urls if set to 1.

tileVersion

Optional tileVersion query parameter. Will return all exports compatible with that tileVersion.

exportType

Optional exportType query parameter. Will return all exports that have the matching exportType.

iTwinJS

Optional iTwinJS query parameter. Will return all exports compatible with that iTwinJS version.

Request headers

prefer

This operation supports return=representation and return=minimal preferences, defaults to return=minimal if not provided.

x-api-host-and-root

Prefix to add to list links.

Authorization

Yes

OAuth access token with itwin-platform scope

Yes

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

Response

Response 200 OK

List of user requested exports.

json

{
    "exports": [{
            "id": "fc3aa1e5-5196-4dd9-a73e-4cfda693e576",
            "displayName": "My iModel",
            "status": "NotStarted",
            "lastModified": "2024-08-22T03:18:43Z"
        },
        {
            "id": "57ea169d-144a-4219-b530-9ce360fd194f",
            "displayName": "My previous iModel",
            "status": "Complete",
            "lastModified": "2024-08-22T03:18:43Z"
        },
        {
            "id": "4777e39e-03a7-48b1-a5c1-4018beaefb25",
            "displayName": "Invalid",
            "status": "Invalid",
            "lastModified": "2024-08-22T03:18:43Z"
        }
    ],
    "_links": {
        "self": {
            "href": "https://api.bentley.com/mesh-export/?$top=100&$skip=0"
        },
        "next": {
            "href": "https://api.bentley.com/mesh-export/?$top=100&$skip=100"
        }
    }
}

Response 401 Unauthorized

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 422 Unprocessable Entity

Cannot retrieve export.

json

{
    "error": {
        "code": "InvalidMeshExportRequest",
        "message": "Cannot retrieve export.",
        "details": [{
                "code": "InvalidParameter",
                "message": "$top must be lower or equal to 1000.",
                "target": "$top"
            },
            {
                "code": "InvalidParameter",
                "message": "iModelId is invalid.",
                "target": "iModelId"
            },
            {
                "code": "InvalidParameter",
                "message": "changesetId is invalid.",
                "target": "changesetId"
            }
        ]
    }
}

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

Link

href

String

Http reference

json

{
    "required": [
        "href"
    ],
    "type": "object",
    "properties": {
        "href": {
            "type": "string",
            "description": "Http reference",
            "example": "https://api.bentley.com/path1/path2/id"
        }
    },
    "additionalProperties": false
}

ExportListLinks

self

Link

json

{
    "required": [
        "self"
    ],
    "type": "object",
    "properties": {
        "self": {
            "$ref": "#/components/schemas/Link"
        },
        "prev": {
            "$ref": "#/components/schemas/Link"
        },
        "next": {
            "$ref": "#/components/schemas/Link"
        }
    },
    "additionalProperties": false
}

ExportListRepresentationResponse

exports

Export[]

Requested export list

_links

ExportListLinks

json

{
    "required": [
        "exports",
        "_links"
    ],
    "type": "object",
    "properties": {
        "exports": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/Export"
            },
            "description": "Requested export list"
        },
        "_links": {
            "$ref": "#/components/schemas/ExportListLinks"
        }
    },
    "additionalProperties": false,
    "example": {
        "exports": [
            {
                "id": "fc3aa1e5-5196-4dd9-a73e-4cfda693e576",
                "displayName": "My iModel",
                "status": "NotStarted",
                "request": {
                    "iModelId": "b80f4fc2-4dbb-42c5-bb1f-f5aace3977dc",
                    "changesetId": "ed94ed9a0704918d36eeb620219f5e17d8858858",
                    "exportType": "3DTiles"
                },
                "_links": {
                    "mesh": {
                        "href": "https://azure.net/blob/fc3aa1e5-5196-4dd9-a73e-4cfda693e576?saskey"
                    }
                }
            },
            {
                "id": "57ea169d-144a-4219-b530-9ce360fd194f",
                "displayName": "My previous iModel",
                "status": "Complete",
                "request": {
                    "iModelId": "b80f4fc2-4dbb-42c5-bb1f-f5aace3977dc",
                    "changesetId": "e3a5dece-c1eb-477c-a782-32a4c43ba2ad",
                    "exportType": "3DTiles"
                },
                "_links": {
                    "mesh": {
                        "href": "https://azure.net/blob/57ea169d-144a-4219-b530-9ce360fd194f?saskey"
                    }
                }
            },
            {
                "id": "4777e39e-03a7-48b1-a5c1-4018beaefb25",
                "displayName": "Invalid",
                "status": "Invalid",
                "error": "Export failed, see linked zipped logs",
                "request": {
                    "iModelId": "b80f4fc2-4dbb-42c5-bb1f-f5aace3977dc",
                    "changesetId": "e3a5dece-c1eb-477c-a782-32a4c43ba2ad",
                    "exportType": "3DTiles"
                },
                "_links": {
                    "mesh": {
                        "href": "https://azure.net/blob/4777e39e-03a7-48b1-a5c1-4018beaefb25?saskey"
                    }
                }
            }
        ],
        "_links": {
            "self": {
                "href": "https://api.bentley.com/mesh-export/?$top=100&$skip=0"
            },
            "next": {
                "href": "https://api.bentley.com/mesh-export/?$top=100&$skip=100"
            }
        }
    }
}

ExportMinimal

String

ID of the export request.

displayName

String

Name of the exported iModel

status

ExportStatus

lastModified

Date-time

Date when job metadata was last modified

json

{
    "required": [
        "id",
        "displayName",
        "status",
        "lastModified"
    ],
    "type": "object",
    "properties": {
        "id": {
            "type": "string",
            "description": "ID of the export request."
        },
        "displayName": {
            "type": "string",
            "description": "Name of the exported iModel"
        },
        "status": {
            "$ref": "#/components/schemas/ExportStatus"
        },
        "lastModified": {
            "type": "string",
            "format": "date-time",
            "description": "Date when job metadata was last modified"
        }
    },
    "additionalProperties": false
}

ExportStatus

Status of the export.

NotStarted

String

InProgress

String

Complete

String

Invalid

String

json

{
    "enum": [
        "NotStarted",
        "InProgress",
        "Complete",
        "Invalid"
    ],
    "type": "string",
    "description": "Status of the export."
}

ExportStatsDisplay

Statistics of the export job. This obsoletes the Consumption type.

iModelSize

Number

Size of the iModel .bin file, in bytes

compressedSize

Number

Size of the exported and compressed tiles, in bytes.

rawSize

Number

Size of the exported tiles, in bytes.

startTime

Date-time

Starting date of the export job, pretty-printed.

duration

Number

Duration of the export job, in milliseconds.

metrics

Object

json

{
    "type": "object",
    "properties": {
        "iModelSize": {
            "type": "number",
            "description": "Size of the iModel .bin file, in bytes"
        },
        "compressedSize": {
            "type": "number",
            "description": "Size of the exported and compressed tiles, in bytes."
        },
        "rawSize": {
            "type": "number",
            "description": "Size of the exported tiles, in bytes."
        },
        "startTime": {
            "type": "string",
            "description": "Starting date of the export job, pretty-printed.",
            "format": "date-time"
        },
        "duration": {
            "type": "number",
            "description": "Duration of the export job, in milliseconds."
        },
        "metrics": {
            "type": "object",
            "additionalProperties": false
        }
    },
    "additionalProperties": false,
    "description": "Statistics of the export job. This obsoletes the Consumption type."
}

Export

String

ID of the export request.

displayName

String

Name of the exported iModel

status

ExportStatus

lastModified

String

Date when job metadata was last modified

request

StartExport

stats

ExportStatsDisplay

error

String

Error message for Invalid exports.

_links.mesh

Link

json

{
    "required": [
        "id",
        "displayName",
        "status",
        "lastModified",
        "request"
    ],
    "type": "object",
    "properties": {
        "id": {
            "type": "string",
            "description": "ID of the export request."
        },
        "displayName": {
            "type": "string",
            "description": "Name of the exported iModel"
        },
        "status": {
            "$ref": "#/components/schemas/ExportStatus"
        },
        "lastModified": {
            "type": "string",
            "description": "Date when job metadata was last modified"
        },
        "request": {
            "$ref": "#/components/schemas/StartExport"
        },
        "stats": {
            "$ref": "#/components/schemas/ExportStatsDisplay"
        },
        "error": {
            "type": "string",
            "description": "Error message for Invalid exports."
        },
        "_links": {
            "type": "object",
            "properties": {
                "mesh": {
                    "$ref": "#/components/schemas/Link"
                }
            },
            "additionalProperties": false
        }
    },
    "additionalProperties": false,
    "example": {
        "id": "fc3aa1e5-5196-4dd9-a73e-4cfda693e576",
        "displayName": "My iModel",
        "status": "Complete",
        "request": {
            "iModelId": "b80f4fc2-4dbb-42c5-bb1f-f5aace3977dc",
            "changesetId": "ed94ed9a0704918d36eeb620219f5e17d8858858",
            "exportType": "3DTiles"
        },
        "_links": {
            "mesh": {
                "href": "https://azure.net/blob/fc3aa1e5-5196-4dd9-a73e-4cfda693e576?saskey"
            }
        }
    }
}

ExportListMinimalResponse

exports

ExportMinimal[]

Requested export list minimal representation.

_links

ExportListLinks

json

{
    "required": [
        "exports",
        "_links"
    ],
    "type": "object",
    "properties": {
        "exports": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/ExportMinimal"
            },
            "description": "Requested export list minimal representation."
        },
        "_links": {
            "$ref": "#/components/schemas/ExportListLinks"
        }
    },
    "additionalProperties": false
}

StartExport exportType

Type of mesh to create, Accepted value are 3DFT, CESIUM, IMODEL and 3DTiles

3DFT

String

IMODEL

String

CESIUM

String

3DTiles

String

json

{
    "enum": [
        "3DFT",
        "IMODEL",
        "CESIUM",
        "3DTiles"
    ],
    "type": "string",
    "description": "Type of mesh to create, Accepted value are 3DFT, CESIUM, IMODEL and 3DTiles",
    "title": "StartExport exportType"
}

StartExport

iModelId

String

ID of the iModel to extract from.

changesetId

String

ID of the changeset to extract from. If omitted, export latest.

StartExport exportType

StartExport-exportType

Type of mesh to create, Accepted value are 3DFT, CESIUM, IMODEL and 3DTiles

lastModified

Date-time

Date when job metadata was last modified

json

{
    "required": [
        "iModelId",
        "changesetId"
    ],
    "type": "object",
    "properties": {
        "iModelId": {
            "type": "string",
            "description": "ID of the iModel to extract from."
        },
        "changesetId": {
            "type": "string",
            "description": "ID of the changeset to extract from. If omitted, export latest."
        },
        "exportType": {
            "enum": [
                "3DFT",
                "IMODEL",
                "CESIUM",
                "3DTiles"
            ],
            "type": "string",
            "description": "Type of mesh to create, Accepted value are 3DFT, CESIUM, IMODEL and 3DTiles",
            "title": "StartExport exportType",
            "$ref": "#/components/schemas/StartExport-exportType"
        },
        "lastModified": {
            "type": "string",
            "format": "date-time",
            "description": "Date when job metadata was last modified"
        }
    },
    "additionalProperties": false,
    "example": {
        "iModelId": "b80f4fc2-4dbb-42c5-bb1f-f5aace3977dc",
        "changesetId": "ed94ed9a0704918d36eeb620219f5e17d8858858",
        "exportType": "3DTiles"
    }
}

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?