Reality Analysis
Download API definition:
This API is a Technical Preview and is available for testing purposes only. Do not use in production.
GET https://qa-api.bentley.com/realitydataanalysis/jobs?$filter[&continuationToken][&$top]

Retrieve list of jobs matching provided filter.

The iTwinId in filter is optional. If it is not provided, this will return jobs created by the same user. However, if the iTwinId is provided and the user has access to it, this will return jobs associated with that specific iTwin.

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 parameters

Name
Required?
Description
$filter
Yes

The $filter query option requests a specific set of jobs. The given filter is evaluated for each job and only job where the filter evaluates to true are returned. Properties supported for filtering: id, iTwinId, name, email, type, state, createdDateTime, inputId, outputId. Supported operators: eq, lt, le, gt, ge, ne, in, and, or. Examples of $filter values: $filter=iTwinId eq dc720f05-e5f7-448b-ae06-765de46f0af1 $filter=inputId in ('482b2968-6a85-4e50-b05c-8acbf828c1bd', '14c03448-bea0-4d76-b53b-4b20bd3f4cbc') $filter=id eq 9e2d27cf-b695-47e9-b7f0-0d47dc3b88ad $filter=createdDateTime gt 2024-06-24T13:00:00Z

continuationToken
No

Parameter that enables continuing to the next page of the previous paged query. This must be passed exactly as it is in the response body's _links.next property.

$top
No

The number of reality analysis jobs to get in each page. Max 1000, but 100 is the default if this parameter is not included.

Request headers

Name
Required?
Description
Authorization
Yes

OAuth access token with itwin-platform scope

Accept
Yes

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

Response 200 OK

OK

json
{
    "jobs": [{
        "state": "unsubmitted",
        "outputs": [{
            "type": "objects2D"
        }],
        "inputs": [{
                "type": "photos",
                "id": "e9803e0e-70ce-4ea6-b2ad-1c653cbf2f76"
            },
            {
                "type": "photoObjectDetector",
                "id": "111d3524-2bd3-46c4-9bf4-e0c650f5f8f2"
            }
        ],
        "options": {
            "minPhotos": 2,
            "useTiePoints": true
        },
        "createdDateTime": "2021-11-04T14:13:27Z",
        "lastModifiedDateTime": "2021-11-04T14:13:27Z",
        "id": "6f51448f-6377-4330-9ab0-f13fe994b3f1",
        "email": "example@email.com",
        "dataCenter": "EastUs",
        "type": "objects2D",
        "name": "My first objects2D job",
        "iTwinId": "510cd1a3-3703-4729-b08c-fecd9c87c3be",
        "costEstimation": {
            "gigaPixels": 2,
            "sceneWidth": 4.5,
            "sceneHeight": 3.0,
            "sceneLength": 1.7,
            "detectorScale": 1.2,
            "detectorCost": 1.4,
            "numberOfPhotos": 150,
            "estimatedCost": 2.1
        }
    }],
    "_links": {
        "next": {
            "href": "https://api.bentley.com/realitydataanalysis/jobs?$filter=iTwinId eq 510cd1a3-3703-4729-b08c-fecd9c87c3be&continuationToken=MzY3ZmY1ZDEtNDEzOS00ZGU1LTg0MjMtN2I5NmVkZDAyN2M0"
        }
    }
}

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 404 Not Found

Not Found

json
{
    "error": {
        "code": "iTwinNotFound",
        "message": "Requested iTwin is not available."
    }
}

Response 422 Unprocessable Entity

The 422 (Unprocessable Entity) status code indicates that the request cannot be processed by the server due to a client error (e.g. malformed request syntax).

json
{
    "error": {
        "code": "InvalidRealityDataAnalysisRequest",
        "message": "Cannot find jobs.",
        "details": [{
            "code": "InvalidParameter",
            "message": "The $top query parameter value must be a positive integer that does not exceed 1000.",
            "target": "$Top"
        }]
    }
}

Response 429 Too many requests

This response indicates that the user has sent too many requests in a given amount of time.

json
{
    "error": {
        "code": "TooManyRequests",
        "message": "More requests were received than the subscription rate-limit allows."
    }
}

Response headers

Name
Description
retry-after

The number of requests exceeds the rate-limit for the client subscription.

Job type

Available job types among 'objects2D', 'segmentation2D', 'segmentation3D', 'segmentationOrthophoto' and 'changeDetection'.

Name
Type
Description
objects2D
String
segmentation2D
String
segmentation3D
String
segmentationOrthophoto
String
changeDetection
String

Job state

Possible state of a job among 'unsubmitted', 'active', 'success', 'failed' and 'cancelled'.

Name
Type
Description
unsubmitted
String
active
String
success
String
failed
String
cancelled
String

Input types

Input types available. Refer to 'Job types' page for per job type list.

Name
Type
Description
photos
String
photoObjectDetector
String
photoSegmentationDetector
String
orthophoto
String
orthophotoSegmentationDetector
String
pointClouds
String
objects2D
String
meshes
String
pointCloudSegmentationDetector
String
clipPolygon
String
segmentation3D
String
segmentation2D
String
pointClouds1
String
pointClouds2
String
meshes1
String
meshes2
String

Job Input

Input description for a job

Name
Type
Description
type

Input name

id
String

Reality Data id of the input

Output types

Output types available. Refer to 'Job types' page for per job type list.

Name
Type
Description
objects2D
String
segmentation2D
String
polygons2D
String
polygons3D
String
exportedPolygons2DSHP
String
exportedPolygons3DDGN
String
exportedPolygons3DCesium
String
lines2D
String
exportedLines2DSHP
String
exportedLines2DDGN
String
objects3D
String
exportedObjects3DDGN
String
exportedObjects3DCesium
String
exportedLocations3DSHP
String
segmentation3D
String
segmentedPointCloud
String
segmentedPhotos
String
exportedSegmentation3DPOD
String
exportedSegmentation3DLAS
String
exportedSegmentation3DLAZ
String
exportedSegmentation3DPLY
String
lines3D
String
exportedLines3DDGN
String
exportedLines3DCesium
String

Job Output

Output description for a job

Name
Type
Description
type

Output name

id
String, null

Reality Data id of the output

Objects2D Options

Options for Object2D job

Name
Type
Description
useTiePoints
Boolean

Improve detection using tie points in orientedPhotos (advanced)

minPhotos
Integer

Minimum number of 2D objects to generate a 3D object (default: 0)

maxDist
Number

Maximum distance between photos and 3D objects (default: 0)

exportSrs
String

SRS used by exports

Segmentation2D Options

Options for Segmentation2D job

Name
Type
Description
minPhotos
Integer

Minimum number of 2D objects to generate a 3D object (default: 0)

computeLineWidth
Boolean

Estimate 3D line width at each vertex

removeSmallComponents
Number

Remove 3D lines with total length smaller than this value

exportSrs
String

SRS used by exports

SegmentationOrthophoto Options

Options for SegmentationOrthophoto job

Segmentation3D Options

Options for Segmentation3D job

Name
Type
Description
computeLineWidth
Boolean

Estimate 3D line width at each vertex

removeSmallComponents
Number

Remove 3D lines with total length smaller than this value

exportSrs
String

SRS used by exports

saveConfidence
String

Save confidence in 3D segmentation

ChangeDetection Options

Options for a ChangeDetection job

Name
Type
Description
colorThresholdLow
Number

Low threshold to detect color changes (hysteresis detection). 0 to ignore color changes

colorThresholdHigh
Number

High threshold to detect color changes (hysteresis detection). 0 to ignore color changes

distThresholdLow
Number

Low threshold to detect spatial changes (hysteresis detection). 0 for automatic setting

distThresholdHigh
Number

High threshold to detect spatial changes (hysteresis detection). 0 for automatic setting

resolution
Number

Target point cloud resolution when starting from meshes

minPoints
Integer

Minimum number of points in a region to be considered as a change

exportSrs
String

SRS used by exports

Error and Warning messages

Model for error and warning messages

Name
Type
Description
code
String

Error or warning message code

title
String

Error or warning message title

message
String

Error or warning message

params
Array

Error or warning message parameters

Execution information

Execution details regarding a job

Name
Type
Description
exitCode
Integer, null

Exit code of the processing

submissionDateTime
Date-time, null

Submission date time of the job

startedDateTime
Date-time, null

Start date time of the job

endedDateTime
Date-time, null

End date time of the job

estimatedUnits
Double, null

Estimated cost of the executed job

errors

Errors, if any produced when processing the job

warnings

Warnings, if any produced when processing the job

Cost Estimation information

Cost estimate based on parameters before job processing

Name
Type
Description
gigaPixels
Double, null

Number of giga pixels in inputs

numberOfPhotos
Int32, null

Number of photos in inputs

sceneWidth
Double, null

Width of the scene

sceneHeight
Double, null

Height of the scene

sceneLength
Double, null

Length of the scene

detectorScale
Double, null

Scale of the detector

detectorCost
Double, null

Cost of the detector

estimatedCost
Double

Estimated Cost of the job using the CostEstimationParameters

Job

Job details

Name
Type
Description
id
String

Job id

email
String

User email address

state

Job state

type

Job type

name
String

Job name

iTwinId
String

ITwin Id

inputs

List of inputs of the job

outputs

List of outputs of the job

createdDateTime
Date-time

Created date-time of the job

lastModifiedDateTime
Date-time

Date-time of the latest modification of the job

executionInformation

Execution Information of the job

costEstimation

Cost estimation before job processing

dataCenter
String

Data center location of the job

Reality Data Analysis Jobs

Jobs

Name
Type
Description
jobs
job[]

Array of jobs

_links

Contains the hyperlink to the next page of results, if applicable

Next Page Link

URL for getting the next page of data, if applicable.

Name
Type
Description
next

URL for getting the next page of results.

link

Name
Type
Description
href
String

Hyperlink container.

DetailedError

Contains error information and an array of more specific errors.

Name
Type
Description
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.

details

Optional array of more specific errors.

Detailed 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.

Name
Type
Description
error

Error Detailed information.

Error

Contains error information.

Name
Type
Description
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.

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.

Name
Type
Description
error

Error information.