Get jobs - Reality Analysis

REST API Overview

Reference

Changelog

Reality Analysis

Download API definition:

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

Get jobs

GET https://dev-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

Request parameters

$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

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

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

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

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

retry-after

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

Definitions

Job type

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

objects2D

String

segmentation2D

String

segmentation3D

String

segmentationOrthophoto

String

changeDetection

String

Job state

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

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.

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

type

inputType

Input name

String

Reality Data id of the input

Output types

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

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

type

outputType

Output name

String, null

Reality Data id of the output

Objects2D Options

Options for Object2D job

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

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

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

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

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

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

ErrorWarningMessage[], null

Errors, if any produced when processing the job

warnings

ErrorWarningMessage[], null

Warnings, if any produced when processing the job

Cost Estimation information

Cost estimate based on parameters before job processing

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

String

Job id

String

User email address

state

Job state

type

jobType

Job type

name

String

Job name

iTwinId

String

ITwin Id

inputs

jobInput[]

List of inputs of the job

outputs

jobOutput[]

List of outputs of the job

options

Any of: objects2DOptions segmentation2DOptions segmentationOrthophotoOptions segmentation3DOptions changeDetectionOptions

Options for this job, must be in sync with type

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

jobs

job[]

Array of jobs

_links

next-page-link, null

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

Next Page Link

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

link

URL for getting the next page of results.

link

href

String

Hyperlink container.

DetailedError

Contains error information and an array of more specific errors.

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

Error[]

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.

error

DetailedError

Error Detailed information.