Get job - Reality Analysis

Reality Analysis

Download API definition:

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

Get job

GET https://api.bentley.com/realitydataanalysis/jobs/{jobId}

Retrieve job details, such as current state, execution information, outputs, etc.

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 headers

Authorization

Yes

OAuth access token with itwin-platform scope

Yes

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

Response 200 OK

json

{
    "job": {
        "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
        }
    }
}

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": "JobNotFound",
        "message": "Requested job is not available."
    }
}

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

Job type

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

objects2D

String

segmentation2D

String

segmentation3D

String

segmentationOrthophoto

String

changeDetection

String

json

{
    "title": "Job type",
    "enum": [
        "objects2D",
        "segmentation2D",
        "segmentation3D",
        "segmentationOrthophoto",
        "changeDetection"
    ],
    "description": "Available job types among 'objects2D', 'segmentation2D', 'segmentation3D', 'segmentationOrthophoto' and 'changeDetection'."
}

Job state

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

unsubmitted

String

active

String

success

String

failed

String

cancelled

String

json

{
    "title": "Job state",
    "enum": [
        "unsubmitted",
        "active",
        "success",
        "failed",
        "cancelled"
    ],
    "description": "Possible state of a job among 'unsubmitted', 'active', 'success', 'failed' and 'cancelled'."
}

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

json

{
    "title": "Input types",
    "enum": [
        "photos",
        "photoObjectDetector",
        "photoSegmentationDetector",
        "orthophoto",
        "orthophotoSegmentationDetector",
        "pointClouds",
        "objects2D",
        "meshes",
        "pointCloudSegmentationDetector",
        "clipPolygon",
        "segmentation3D",
        "segmentation2D",
        "pointClouds1",
        "pointClouds2",
        "meshes1",
        "meshes2"
    ],
    "description": "Input types available. Refer to 'Job types' page for per job type list."
}

Job Input

Input description for a job

type

inputType

Input name

String

Reality Data id of the input

json

{
    "type": "object",
    "title": "Job Input",
    "description": "Input description for a job",
    "properties": {
        "type": {
            "$ref": "#/components/schemas/inputType",
            "description": "Input name"
        },
        "id": {
            "type": "string",
            "description": "Reality Data id of the input"
        }
    },
    "required": [
        "type",
        "id"
    ],
    "additionalProperties": false
}

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

exportedPolygons2DGeoJSON

String

exportedPolygons3DCesium

String

exportedPolygons3DGeoJSON

String

lines2D

String

exportedLines2DSHP

String

exportedLines2DDGN

String

exportedLines2DGeoJSON

String

objects3D

String

exportedObjects3DDGN

String

exportedObjects3DCesium

String

exportedObjects3DGeoJSON

String

exportedLocations3DSHP

String

exportedLocations3DGeoJSON

String

segmentation3D

String

segmentedPointCloud

String

segmentedPhotos

String

exportedSegmentation3DPOD

String

exportedSegmentation3DLAS

String

exportedSegmentation3DLAZ

String

exportedSegmentation3DPLY

String

lines3D

String

exportedLines3DDGN

String

exportedLines3DCesium

String

exportedLines3DGeoJSON

String

json

{
    "title": "Output types",
    "enum": [
        "objects2D",
        "segmentation2D",
        "polygons2D",
        "polygons3D",
        "exportedPolygons2DSHP",
        "exportedPolygons3DDGN",
        "exportedPolygons2DGeoJSON",
        "exportedPolygons3DCesium",
        "exportedPolygons3DGeoJSON",
        "lines2D",
        "exportedLines2DSHP",
        "exportedLines2DDGN",
        "exportedLines2DGeoJSON",
        "objects3D",
        "exportedObjects3DDGN",
        "exportedObjects3DCesium",
        "exportedObjects3DGeoJSON",
        "exportedLocations3DSHP",
        "exportedLocations3DGeoJSON",
        "segmentation3D",
        "segmentedPointCloud",
        "segmentedPhotos",
        "exportedSegmentation3DPOD",
        "exportedSegmentation3DLAS",
        "exportedSegmentation3DLAZ",
        "exportedSegmentation3DPLY",
        "lines3D",
        "exportedLines3DDGN",
        "exportedLines3DCesium",
        "exportedLines3DGeoJSON"
    ],
    "description": "Output types available. Refer to 'Job types' page for per job type list."
}

Job Output

Output description for a job

type

outputType

Output name

String, null

Reality Data id of the output

json

{
    "type": "object",
    "title": "Job Output",
    "description": "Output description for a job",
    "properties": {
        "type": {
            "$ref": "#/components/schemas/outputType",
            "description": "Output name"
        },
        "id": {
            "type": "string",
            "description": "Reality Data id of the output",
            "nullable": true
        }
    },
    "required": [
        "type"
    ],
    "additionalProperties": false
}

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

json

{
    "type": "object",
    "title": "Objects2D Options",
    "description": "Options for Object2D job",
    "properties": {
        "useTiePoints": {
            "type": "boolean",
            "description": "Improve detection using tie points in orientedPhotos (advanced)"
        },
        "minPhotos": {
            "type": "integer",
            "description": "Minimum number of 2D objects to generate a 3D object (default: 0)"
        },
        "maxDist": {
            "type": "number",
            "description": "Maximum distance between photos and 3D objects (default: 0)"
        },
        "exportSrs": {
            "type": "string",
            "description": "SRS used by exports"
        }
    },
    "additionalProperties": false
}

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

json

{
    "type": "object",
    "title": "Segmentation2D Options",
    "description": "Options for Segmentation2D job",
    "properties": {
        "minPhotos": {
            "type": "integer",
            "description": "Minimum number of 2D objects to generate a 3D object (default: 0)"
        },
        "computeLineWidth": {
            "type": "boolean",
            "description": "Estimate 3D line width at each vertex"
        },
        "removeSmallComponents": {
            "type": "number",
            "description": "Remove 3D lines with total length smaller than this value"
        },
        "exportSrs": {
            "type": "string",
            "description": "SRS used by exports"
        }
    },
    "additionalProperties": false
}

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

json

{
    "type": "object",
    "title": "Segmentation3D Options",
    "description": "Options for Segmentation3D job",
    "properties": {
        "computeLineWidth": {
            "type": "boolean",
            "description": "Estimate 3D line width at each vertex"
        },
        "removeSmallComponents": {
            "type": "number",
            "description": "Remove 3D lines with total length smaller than this value"
        },
        "exportSrs": {
            "type": "string",
            "description": "SRS used by exports"
        },
        "saveConfidence": {
            "type": "string",
            "description": "Save confidence in 3D segmentation"
        }
    },
    "additionalProperties": false
}

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

json

{
    "type": "object",
    "title": "ChangeDetection Options",
    "description": "Options for a ChangeDetection job",
    "properties": {
        "colorThresholdLow": {
            "type": "number",
            "description": "Low threshold to detect color changes (hysteresis detection). 0 to ignore color changes"
        },
        "colorThresholdHigh": {
            "type": "number",
            "description": "High threshold to detect color changes (hysteresis detection). 0 to ignore color changes"
        },
        "distThresholdLow": {
            "type": "number",
            "description": "Low threshold to detect spatial changes (hysteresis detection). 0 for automatic setting"
        },
        "distThresholdHigh": {
            "type": "number",
            "description": "High threshold to detect spatial changes (hysteresis detection). 0 for automatic setting"
        },
        "resolution": {
            "type": "number",
            "description": "Target point cloud resolution when starting from meshes"
        },
        "minPoints": {
            "type": "integer",
            "description": "Minimum number of points in a region to be considered as a change"
        },
        "exportSrs": {
            "type": "string",
            "description": "SRS used by exports"
        }
    },
    "additionalProperties": false
}

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

json

{
    "title": "Error and Warning messages",
    "description": "Model for error and warning messages",
    "type": "object",
    "properties": {
        "code": {
            "type": "string",
            "description": "Error or warning message code"
        },
        "title": {
            "type": "string",
            "description": "Error or warning message title"
        },
        "message": {
            "type": "string",
            "description": "Error or warning message"
        },
        "params": {
            "type": "array",
            "description": "Error or warning message parameters"
        }
    },
    "additionalProperties": false
}

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

json

{
    "title": "Execution information",
    "description": "Execution details regarding a job",
    "type": "object",
    "properties": {
        "exitCode": {
            "type": "integer",
            "description": "Exit code of the processing",
            "nullable": true
        },
        "submissionDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "Submission date time of the job",
            "nullable": true
        },
        "startedDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "Start date time of the job",
            "nullable": true
        },
        "endedDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "End date time of the job",
            "nullable": true
        },
        "estimatedUnits": {
            "type": "number",
            "format": "double",
            "description": "Estimated cost of the executed job",
            "nullable": true
        },
        "errors": {
            "type": "array",
            "description": "Errors, if any produced when processing the job",
            "items": {
                "$ref": "#/components/schemas/ErrorWarningMessage"
            },
            "nullable": true
        },
        "warnings": {
            "type": "array",
            "description": "Warnings, if any produced when processing the job",
            "items": {
                "$ref": "#/components/schemas/ErrorWarningMessage"
            },
            "nullable": true
        }
    },
    "additionalProperties": false
}

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

json

{
    "type": "object",
    "title": "Cost Estimation information",
    "description": "Cost estimate based on parameters before job processing",
    "properties": {
        "gigaPixels": {
            "description": "Number of giga pixels in inputs",
            "type": "number",
            "format": "double",
            "nullable": true
        },
        "numberOfPhotos": {
            "type": "integer",
            "description": "Number of photos in inputs",
            "format": "int32",
            "nullable": true
        },
        "sceneWidth": {
            "description": "Width of the scene",
            "type": "number",
            "format": "double",
            "nullable": true
        },
        "sceneHeight": {
            "description": "Height of the scene",
            "type": "number",
            "format": "double",
            "nullable": true
        },
        "sceneLength": {
            "description": "Length of the scene",
            "type": "number",
            "format": "double",
            "nullable": true
        },
        "detectorScale": {
            "description": "Scale of the detector",
            "type": "number",
            "format": "double",
            "nullable": true
        },
        "detectorCost": {
            "description": "Cost of the detector",
            "type": "number",
            "format": "double",
            "nullable": true
        },
        "estimatedCost": {
            "type": "number",
            "description": "Estimated Cost of the job using the CostEstimationParameters",
            "format": "double"
        }
    },
    "additionalProperties": false
}

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

json

{
    "type": "object",
    "title": "Job",
    "description": "Job details",
    "properties": {
        "id": {
            "type": "string",
            "description": "Job id"
        },
        "email": {
            "type": "string",
            "description": "User email address"
        },
        "state": {
            "$ref": "#/components/schemas/state",
            "description": "Job state"
        },
        "type": {
            "$ref": "#/components/schemas/jobType",
            "description": "Job type"
        },
        "name": {
            "type": "string",
            "description": "Job name"
        },
        "iTwinId": {
            "type": "string",
            "description": "ITwin Id"
        },
        "inputs": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/jobInput"
            },
            "description": "List of inputs of the job"
        },
        "outputs": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/jobOutput"
            },
            "description": "List of outputs of the job"
        },
        "options": {
            "anyOf": [
                {
                    "$ref": "#/components/schemas/objects2DOptions"
                },
                {
                    "$ref": "#/components/schemas/segmentation2DOptions"
                },
                {
                    "$ref": "#/components/schemas/segmentationOrthophotoOptions"
                },
                {
                    "$ref": "#/components/schemas/segmentation3DOptions"
                },
                {
                    "$ref": "#/components/schemas/changeDetectionOptions"
                }
            ],
            "description": "Options for this job, must be in sync with type"
        },
        "createdDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "Created date-time of the job"
        },
        "lastModifiedDateTime": {
            "type": "string",
            "format": "date-time",
            "description": "Date-time of the latest modification of the job"
        },
        "executionInformation": {
            "$ref": "#/components/schemas/executionInformation",
            "description": "Execution Information of the job"
        },
        "costEstimation": {
            "$ref": "#/components/schemas/costEstimation",
            "description": "Cost estimation before job processing"
        },
        "dataCenter": {
            "type": "string",
            "description": "Data center location of the job"
        }
    },
    "required": [
        "id",
        "email",
        "state",
        "type",
        "name",
        "iTwinId",
        "inputs",
        "outputs",
        "createdDateTime",
        "lastModifiedDateTime",
        "costEstimation",
        "dataCenter"
    ],
    "additionalProperties": false
}

Job response

job

Complete job details

json

{
    "title": "Job response",
    "type": "object",
    "properties": {
        "job": {
            "$ref": "#/components/schemas/job",
            "description": "Complete job details"
        }
    },
    "required": [
        "job"
    ],
    "additionalProperties": false
}

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?

Parameters

Authentication

Request

Request parameters

Request headers

Response

Response 200 OK

Response 401 Unauthorized

Response 404 Not Found

Response 429 Too many requests

Response headers

Definitions

Job type

Job state

Input types

Job Input

Output types

Job Output

Objects2D Options

Segmentation2D Options

SegmentationOrthophoto Options

Segmentation3D Options

ChangeDetection Options

Error and Warning messages

Execution information

Cost Estimation information

Job

Job response

Error

Error Response