---
title: Run an analysis
source: https://infrared.city/docs/sdk/1.0/api/typescript/run-an-analysis/
---

# Run an analysis

<a id="analysisservice"></a>

## AnalysisService

Import from `@infrared-city/infrared-sdk-ts`.

Submits requests already written with the API's own keys; available as
`InfraredClient.analyses`.

### Constructors

<a id="analysisservice-constructor"></a>

#### Constructor

> **new AnalysisService**(`jobs`): `AnalysisService`

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `jobs` | [`JobsService`](run-an-analysis.md#jobsservice) | The jobs service that sends the request. |

##### Returns

`AnalysisService`

### Methods

<a id="analysisservice-execute"></a>

#### execute()

> **execute**(`payload`, `options?`): `Promise`&lt;[`Job`](run-an-analysis.md#job)&gt;

Submits a request that already uses the API's own keys; does not wait.
Returns the accepted `Job`, or rejects with a `TypeError` when the payload
is not an object or has no `"analysis-type"`.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `payload` | [`WireAnalysisRequest`](requests.md#wireanalysisrequest) |
| `options` | [`SubmitOptions`](requests.md#submitoptions) |

##### Returns

`Promise`&lt;[`Job`](run-an-analysis.md#job)&gt;

***

<a id="areabatchpreview"></a>

## AreaBatchPreview

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

The jobs, estimated time and estimated cost of an area run, from `previewAreaBatches`.

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="areabatchpreview-estimatedcosttokens"></a> `estimatedCostTokens` | `readonly` | `number` | Estimated cost in tokens. |
| <a id="areabatchpreview-estimatedtimes"></a> `estimatedTimeS` | `readonly` | `number` | Estimated run time in seconds. |
| <a id="areabatchpreview-plannedjobcount"></a> `plannedJobCount` | `readonly` | `number` | The number of jobs the run would submit. Price from this, not `tileCount`, on a facade run. |
| <a id="areabatchpreview-sensorcount"></a> `sensorCount?` | `readonly` | `number` | Total sensors across the planned facade batches, or `undefined` for a grid preview. |
| <a id="areabatchpreview-tilecount"></a> `tileCount` | `readonly` | `number` | Non-empty tiles on the grid. Equal to `plannedJobCount` on a grid run. |

***

<a id="areajob"></a>

## AreaJob

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

The job record of one tile inside an area schedule. The schedule's structure is fixed, but the
job values are updated as polling proceeds.

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="areajob-binary"></a> `binary?` | `public` | [`BinaryAcknowledgement`](requests.md#binaryacknowledgement) | The service's acknowledgement of a binary submission, when one was used. |
| <a id="areajob-col"></a> `col` | `readonly` | `number` | Column of the tile in the tile grid. |
| <a id="areajob-error"></a> `error?` | `public` | `string` | Why the job failed or was skipped, when it did. |
| <a id="areajob-invalidreference"></a> `invalidReference?` | `public` | `boolean` | True when this accepted reference cannot produce a trusted result. |
| <a id="areajob-jobid"></a> `jobId?` | `public` | `string` | The job id assigned by the service, once the submission was accepted. |
| <a id="areajob-lastjobsnapshot"></a> `lastJobSnapshot?` | `public` | [`Job`](run-an-analysis.md#job) | The most recent status the service reported for the job. |
| <a id="areajob-result"></a> `result?` | `public` | `Record`&lt;`string`, `unknown`&gt; | The job's stored result, when one was kept. |
| <a id="areajob-row"></a> `row` | `readonly` | `number` | Row of the tile in the tile grid. |
| <a id="areajob-status"></a> `status` | `public` | [`TileJobStatus`](run-an-analysis.md#tilejobstatus) | Current state of the job. |
| <a id="areajob-tileid"></a> `tileId` | `readonly` | `string` | Identifier of the tile this job covers. |

***

<a id="areajobsservice"></a>

## AreaJobsService

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

> **AreaJobsService** = `Pick`&lt;[`JobsService`](run-an-analysis.md#jobsservice), `"prepareSubmission"` \| `"preflightPrepared"` \| `"submitPrepared"` \| `"getStatus"`&gt; & `object`

The job operations an area run needs: prepare, pre-check, submit and read
the status of a job. `InfraredClient.jobs` satisfies it; a custom or mock
service only has to provide the four required methods.

### Type Declaration

| Name | Type | Description |
| ------ | ------ | ------ |
| `binaryCapability()?` | (`signal?`) => `Promise`&lt;[`BinaryCapability`](requests.md#binarycapability)&gt; | Reads the API's capability document, which decides whether a part of a daylight-factor run can use the binary route. Optional: without it the parts stay on the JSON route. A binary area run reads it once to check its route before the first paid POST. |
| `captures?` | [`FacadeCaptures`](facade-layout.md#facadecaptures) | The client's cache of facade captures and layouts. Optional: without it nothing is captured. |
| `releasePreflight()?` | (`prepared`) => `void` | Frees what a pre-check is holding for tiles that are then not submitted. Optional: a service that retains nothing has nothing to free. |

***

<a id="areamergejobsservice"></a>

## AreaMergeJobsService

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

> **AreaMergeJobsService** = `Pick`&lt;[`JobsService`](run-an-analysis.md#jobsservice), `"getStatus"` \| `"downloadResults"`&gt; & `object`

The jobs service `mergeAreaJobs` needs: it reads job status and downloads job results.
`InfraredClient.jobs` satisfies it.

### Type Declaration

| Name | Type | Description |
| ------ | ------ | ------ |
| `captures?` | [`FacadeCaptures`](facade-layout.md#facadecaptures) | The client's own facade capture and layout cache. Optional: when absent, no job inputs were captured and no cell triangles are synthesized. |

***

<a id="areamergeoptions"></a>

## AreaMergeOptions

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

Options for `mergeAreaJobs`.

### Extended by

- [`RunAreaAndWaitOptions`](run-an-analysis.md#runareaandwaitoptions)

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="areamergeoptions-block"></a> `block?` | `readonly` | `number` | Largest block, in cells per side, that the directional strategies process at once; at least 1. It trades speed against memory only: the result is the same for any value. Default 928. |
| <a id="areamergeoptions-logger"></a> `logger?` | `readonly` | [`Logger`](client.md#logger) | Logger that a tile dropped from the merge is warned through. `InfraredClient` passes its own. |
| <a id="areamergeoptions-maxworkers"></a> `maxWorkers?` | `readonly` | `number` | Maximum parallel requests, a positive whole number. Default 5 for status checks and 8 for downloads. |
| <a id="areamergeoptions-signal"></a> `signal?` | `readonly` | `AbortSignal` | Aborts the merge when signalled. |
| <a id="areamergeoptions-strategy"></a> `strategy?` | `readonly` | `"default"` \| `"directional"` \| `"directional_blend"` | How overlapping tiles are blended. Default `"default"`. `"directional"` and `"directional_blend"` apply to wind-speed analyses only and require `windDirectionDeg`. |
| <a id="areamergeoptions-winddirectiondeg"></a> `windDirectionDeg?` | `readonly` | `number` | Wind direction in degrees. Required for the directional strategies. |

***

<a id="areapreview"></a>

## AreaPreview

Import from `@infrared-city/infrared-sdk-ts`.

A quick estimate of an area run, from `InfraredClient.previewArea`.

### Extended by

- [`AreaPreviewWithPricing`](run-an-analysis.md#areapreviewwithpricing)

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="areapreview-estimatedcosttokens"></a> `estimatedCostTokens` | `readonly` | `number` | The estimated cost in tokens. |
| <a id="areapreview-estimatedtimes"></a> `estimatedTimeS` | `readonly` | `number` | A rough run time in seconds. |
| <a id="areapreview-tilecount"></a> `tileCount` | `readonly` | `number` | The number of non-empty tiles, each of which is one billed job. |

***

<a id="areapreviewwithpricing"></a>

## AreaPreviewWithPricing

Import from `@infrared-city/infrared-sdk-ts`.

An `AreaPreview` priced with the API's current price list, from
`InfraredClient.previewAreaWithPricing`.

### Extends

- [`AreaPreview`](run-an-analysis.md#areapreview)

### Properties

| Property | Modifier | Type | Description | Inherited from |
| ------ | ------ | ------ | ------ | ------ |
| <a id="areapreviewwithpricing-estimatedcosttokens"></a> `estimatedCostTokens` | `readonly` | `number` | The estimated cost in tokens. | [`AreaPreview`](run-an-analysis.md#areapreview).[`estimatedCostTokens`](run-an-analysis.md#areapreview-estimatedcosttokens) |
| <a id="areapreviewwithpricing-estimatedtimes"></a> `estimatedTimeS` | `readonly` | `number` | A rough run time in seconds. | [`AreaPreview`](run-an-analysis.md#areapreview).[`estimatedTimeS`](run-an-analysis.md#areapreview-estimatedtimes) |
| <a id="areapreviewwithpricing-pricingsource"></a> `pricingSource` | `readonly` | `"remote"` \| `"fallback"` | `"remote"` when the price came from the API, `"fallback"` when it could not be fetched and the default was used. | - |
| <a id="areapreviewwithpricing-pricingversion"></a> `pricingVersion?` | `readonly` | `string` | The version of the price list used. Present only when `pricingSource` is `"remote"` and the list has a version. | - |
| <a id="areapreviewwithpricing-tilecount"></a> `tileCount` | `readonly` | `number` | The number of non-empty tiles, each of which is one billed job. | [`AreaPreview`](run-an-analysis.md#areapreview).[`tileCount`](run-an-analysis.md#areapreview-tilecount) |
| <a id="areapreviewwithpricing-tokensperjob"></a> `tokensPerJob` | `readonly` | `number` | The tokens charged for one job of the previewed analysis. | - |

***

<a id="areaschedule"></a>

## AreaSchedule

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

Everything needed to follow, merge or retry an area run: its jobs, polygon and the identity
values that guard a retry. It can be saved with `areaScheduleToJSON` and restored with
`areaScheduleFromJSON`. Job values stay mutable so polling can update them.

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="areaschedule-analysistype"></a> `analysisType` | `readonly` | `string` | The analysis type of the run. |
| <a id="areaschedule-attempts"></a> `attempts?` | `readonly` | `Readonly`&lt;`Record`&lt;`string`, `number`&gt;&gt; | The attempt number of the current job or submission of each tile key. A missing key is attempt 1. |
| <a id="areaschedule-batchingpolicyversion"></a> `batchingPolicyVersion?` | `readonly` | `number` | Version of the facade batching policy; set on facade runs. |
| <a id="areaschedule-batchmembership"></a> `batchMembership?` | `readonly` | `Readonly`&lt;`Record`&lt;`string`, readonly `string`\[\]&gt;&gt; | The building ids in each facade batch, by batch key. |
| <a id="areaschedule-batchsensorcounts"></a> `batchSensorCounts?` | `readonly` | `Readonly`&lt;`Record`&lt;`string`, `number`&gt;&gt; | The number of sensors in each facade batch, by batch key. |
| <a id="areaschedule-confighash"></a> `configHash` | `readonly` | `string` | Hash of the run's configuration. A retry must produce the same value. |
| <a id="areaschedule-failedsubmissions"></a> `failedSubmissions` | `readonly` | readonly `string`\[\] | Ids of the tiles whose submission failed. |
| <a id="areaschedule-geometryprobejobids"></a> `geometryProbeJobIds?` | `readonly` | readonly `string`\[\] | Job ids of capability-probe jobs written by older SDK versions. This SDK submits none. A schedule saved by an older version still loads, but cannot be resumed. |
| <a id="areaschedule-geometryprobeuncertain"></a> `geometryProbeUncertain?` | `readonly` | `boolean` | Set by older SDK versions when a capability probe had an unknown outcome. |
| <a id="areaschedule-gridshape"></a> `gridShape` | `readonly` | readonly \[`number`, `number`\] | The tile grid size as `[rows, columns]`. |
| <a id="areaschedule-invalidreferencesubmissions"></a> `invalidReferenceSubmissions?` | `readonly` | readonly `string`\[\] | Referenced jobs retained for billing and support, never polled or merged. |
| <a id="areaschedule-jobs"></a> `jobs` | `readonly` | `ReadonlyMap`&lt;`string`, [`AreaJob`](run-an-analysis.md#areajob)&gt; | The job record of each tile, by tile id. |
| <a id="areaschedule-maxsensorsperjob"></a> `maxSensorsPerJob?` | `readonly` | `number` | Maximum number of sensors in one job of a facade run. |
| <a id="areaschedule-polygon"></a> `polygon` | `readonly` | [`Polygon`](tiling.md#polygon) | The polygon the run covers. |
| <a id="areaschedule-runid"></a> `runId?` | `readonly` | `string` | Identifier of the run, made once per schedule and kept across every `retryFrom`. Absent on a schedule written before this field existed; a retry of one then gets a fresh id. |
| <a id="areaschedule-schedulecontractversion"></a> `scheduleContractVersion?` | `readonly` | `number` | Version of the schedule record format, used to refuse a retry of a schedule that an older SDK wrote. Absent on a schedule written before the field existed. |
| <a id="areaschedule-siteidentity"></a> `siteIdentity?` | `readonly` | `string` | Digest of the prepared site inputs; absent on older schedules or without SHA-256. |
| <a id="areaschedule-submissionabortstatus"></a> `submissionAbortStatus` | `readonly` | `number` \| `null` | The HTTP status that stopped submission early (for example 402), or `null` when submission was not aborted. |
| <a id="areaschedule-surfacefields"></a> `surfaceFields?` | `readonly` | `boolean` | True for a facade or roof run. |
| <a id="areaschedule-terraincontextmarginm"></a> `terrainContextMarginM?` | `readonly` | `number` | Margin of terrain context around each tile, in metres. |
| <a id="areaschedule-tilepositions"></a> `tilePositions` | `readonly` | readonly [`TilePosition`](run-an-analysis.md#tileposition)\[\] | The position of each tile in the grid. |
| <a id="areaschedule-transport"></a> `transport?` | `readonly` | `"json"` \| `"binary"` | How requests were sent: `"json"` or `"binary"`. |
| <a id="areaschedule-uncertainsubmissions"></a> `uncertainSubmissions?` | `readonly` | readonly `string`\[\] | Entries whose POST may have been accepted. Never retry these automatically. |
| <a id="areaschedule-weatheridentity"></a> `weatherIdentity?` | `readonly` | `string` | Identity of the weather these tiles were computed against: the submitted weather columns, the location and the time window. Absent for an analysis that reads no weather. A retry compares it with the weather it would submit, so a resume cannot combine tiles computed against different weather into one grid. It is kept on the client and never sent. |
| <a id="areaschedule-webhookevents"></a> `webhookEvents?` | `readonly` | readonly `string`\[\] | The job events that trigger `webhookUrl`. |
| <a id="areaschedule-webhookurl"></a> `webhookUrl?` | `readonly` | `string` | The URL the API calls when a job reaches one of `webhookEvents`. |
| <a id="areaschedule-wireversion"></a> `wireVersion?` | `readonly` | `1` | Version of the binary wire format; present only with the binary transport. |

***

<a id="areaschedulefromjson"></a>

## areaScheduleFromJSON

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

> **areaScheduleFromJSON**(`value`): [`AreaSchedule`](run-an-analysis.md#areaschedule)

Rebuilds a frozen schedule from the JSON saved by `areaScheduleToJSON`, validating it.

### Parameters

| Parameter | Type |
| ------ | ------ |
| `value` | `unknown` |

### Returns

[`AreaSchedule`](run-an-analysis.md#areaschedule)

### Throws

when the JSON is not a valid area schedule.

***

<a id="areaschedulejson"></a>

## AreaScheduleJSON

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

The JSON form of an `AreaSchedule`, as written by `areaScheduleToJSON`. Its fields match
`AreaSchedule`, with `jobs` stored as an array of `[tileId, job]` pairs.

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="areaschedulejson-analysistype"></a> `analysisType` | `readonly` | `string` | See `AreaSchedule.analysisType`. |
| <a id="areaschedulejson-attempts"></a> `attempts?` | `readonly` | `Readonly`&lt;`Record`&lt;`string`, `number`&gt;&gt; | See `AreaSchedule.attempts`. |
| <a id="areaschedulejson-batchingpolicyversion"></a> `batchingPolicyVersion?` | `readonly` | `number` | See `AreaSchedule.batchingPolicyVersion`. |
| <a id="areaschedulejson-batchmembership"></a> `batchMembership?` | `readonly` | `Readonly`&lt;`Record`&lt;`string`, readonly `string`\[\]&gt;&gt; | See `AreaSchedule.batchMembership`. |
| <a id="areaschedulejson-batchsensorcounts"></a> `batchSensorCounts?` | `readonly` | `Readonly`&lt;`Record`&lt;`string`, `number`&gt;&gt; | See `AreaSchedule.batchSensorCounts`. |
| <a id="areaschedulejson-confighash"></a> `configHash` | `readonly` | `string` | See `AreaSchedule.configHash`. |
| <a id="areaschedulejson-failedsubmissions"></a> `failedSubmissions` | `readonly` | readonly `string`\[\] | See `AreaSchedule.failedSubmissions`. |
| <a id="areaschedulejson-geometryprobejobids"></a> `geometryProbeJobIds?` | `readonly` | readonly `string`\[\] | See `AreaSchedule.geometryProbeJobIds`. |
| <a id="areaschedulejson-geometryprobeuncertain"></a> `geometryProbeUncertain?` | `readonly` | `boolean` | See `AreaSchedule.geometryProbeUncertain`. |
| <a id="areaschedulejson-gridshape"></a> `gridShape` | `readonly` | readonly \[`number`, `number`\] | See `AreaSchedule.gridShape`. |
| <a id="areaschedulejson-invalidreferencesubmissions"></a> `invalidReferenceSubmissions?` | `readonly` | readonly `string`\[\] | See `AreaSchedule.invalidReferenceSubmissions`. |
| <a id="areaschedulejson-jobs"></a> `jobs` | `readonly` | \[`string`, [`AreaJob`](run-an-analysis.md#areajob)\]\[\] | The job record of each tile, as `[tileId, job]` pairs. |
| <a id="areaschedulejson-maxsensorsperjob"></a> `maxSensorsPerJob?` | `readonly` | `number` | See `AreaSchedule.maxSensorsPerJob`. |
| <a id="areaschedulejson-polygon"></a> `polygon` | `readonly` | [`Polygon`](tiling.md#polygon) | See `AreaSchedule.polygon`. |
| <a id="areaschedulejson-runid"></a> `runId?` | `readonly` | `string` | See `AreaSchedule.runId`. |
| <a id="areaschedulejson-schedulecontractversion"></a> `scheduleContractVersion?` | `readonly` | `number` | See `AreaSchedule.scheduleContractVersion`. |
| <a id="areaschedulejson-siteidentity"></a> `siteIdentity?` | `readonly` | `string` | See `AreaSchedule.siteIdentity`. |
| <a id="areaschedulejson-submissionabortstatus"></a> `submissionAbortStatus` | `readonly` | `number` \| `null` | See `AreaSchedule.submissionAbortStatus`. |
| <a id="areaschedulejson-surfacefields"></a> `surfaceFields?` | `readonly` | `boolean` | See `AreaSchedule.surfaceFields`. |
| <a id="areaschedulejson-terraincontextmarginm"></a> `terrainContextMarginM?` | `readonly` | `number` | See `AreaSchedule.terrainContextMarginM`. |
| <a id="areaschedulejson-tilepositions"></a> `tilePositions` | `readonly` | readonly [`TilePosition`](run-an-analysis.md#tileposition)\[\] | See `AreaSchedule.tilePositions`. |
| <a id="areaschedulejson-transport"></a> `transport?` | `readonly` | `"json"` \| `"binary"` | See `AreaSchedule.transport`. |
| <a id="areaschedulejson-uncertainsubmissions"></a> `uncertainSubmissions?` | `readonly` | readonly `string`\[\] | See `AreaSchedule.uncertainSubmissions`. |
| <a id="areaschedulejson-weatheridentity"></a> `weatherIdentity?` | `readonly` | `string` | See `AreaSchedule.weatherIdentity`. |
| <a id="areaschedulejson-webhookevents"></a> `webhookEvents?` | `readonly` | readonly `string`\[\] | See `AreaSchedule.webhookEvents`. |
| <a id="areaschedulejson-webhookurl"></a> `webhookUrl?` | `readonly` | `string` | See `AreaSchedule.webhookUrl`. |
| <a id="areaschedulejson-wireversion"></a> `wireVersion?` | `readonly` | `1` | See `AreaSchedule.wireVersion`. |

***

<a id="areascheduletojson"></a>

## areaScheduleToJSON

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

> **areaScheduleToJSON**(`schedule`): [`AreaScheduleJSON`](run-an-analysis.md#areaschedulejson)

Converts a schedule to plain JSON for saving; read it back with `areaScheduleFromJSON`.

### Parameters

| Parameter | Type |
| ------ | ------ |
| `schedule` | [`AreaSchedule`](run-an-analysis.md#areaschedule) |

### Returns

[`AreaScheduleJSON`](run-an-analysis.md#areaschedulejson)

***

<a id="areastate"></a>

## AreaState

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

Progress of an area run: how many of its jobs are in each state.

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="areastate-completedcount"></a> `completedCount` | `readonly` | `number` | Jobs that completed. |
| <a id="areastate-failedcount"></a> `failedCount` | `readonly` | `number` | Jobs that failed. |
| <a id="areastate-iscomplete"></a> `isComplete` | `readonly` | `boolean` | True when no job is pending or running. |
| <a id="areastate-pendingcount"></a> `pendingCount` | `readonly` | `number` | Jobs not yet running. |
| <a id="areastate-runningcount"></a> `runningCount` | `readonly` | `number` | Jobs currently running. |
| <a id="areastate-skippedcount"></a> `skippedCount` | `readonly` | `number` | Jobs that were skipped or are no longer polled. |
| <a id="areastate-totalcount"></a> `totalCount` | `readonly` | `number` | Total number of jobs. |

***

<a id="areastatusservice"></a>

## AreaStatusService

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

> **AreaStatusService** = `Pick`&lt;[`JobsService`](run-an-analysis.md#jobsservice), `"getStatus"`&gt; & `object`

The status operations `checkAreaState` and `runAreaAndWait` need.
`InfraredClient.jobs` satisfies it.

### Type Declaration

| Name | Type | Description |
| ------ | ------ | ------ |
| `batchedStatusSupported?` | `boolean` | Whether a status sweep costs a fixed couple of requests, not one per job. `runAreaAndWait` uses it to choose its poll interval. |
| `captures?` | `Pick`&lt;[`FacadeCaptures`](facade-layout.md#facadecaptures), `"forget"` \| `"forgetSchedule"`&gt; | The client's facade capture cache. Optional: the run releases the captures of a job that failed and of a run that fails or is aborted. |
| `getStatusBatch?` | [`JobsService`](run-an-analysis.md#jobsservice)\[`"getStatusBatch"`\] | Reads the status of many jobs in one request. Optional: without it each job is read on its own. |

***

<a id="areasubmissionplan"></a>

## AreaSubmissionPlan

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

The plan for one area run: the tiles, the requests built for them and the
identity used to resume the run. `submitAreaPlan` sends it.

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="areasubmissionplan-analysistype"></a> `analysisType` | `readonly` | `string` | The analysis the run performs. |
| <a id="areasubmissionplan-batchingpolicyversion"></a> `batchingPolicyVersion?` | `readonly` | `2` | - |
| <a id="areasubmissionplan-batchmembership"></a> `batchMembership?` | `readonly` | `Readonly`&lt;`Record`&lt;`string`, readonly `string`\[\]&gt;&gt; | - |
| <a id="areasubmissionplan-batchsensorcounts"></a> `batchSensorCounts?` | `readonly` | `Readonly`&lt;`Record`&lt;`string`, `number`&gt;&gt; | - |
| <a id="areasubmissionplan-confighash"></a> `configHash` | `readonly` | `string` | Digest of the settings the plan was built with. |
| <a id="areasubmissionplan-entries"></a> `entries` | `readonly` | readonly `SubmissionEntry`\[\] | The requests to send, one per job. |
| <a id="areasubmissionplan-gridshape"></a> `gridShape` | `readonly` | readonly \[`number`, `number`\] | Rows and columns of the tile grid. |
| <a id="areasubmissionplan-localcelltris"></a> `localCellTris?` | `readonly` | `boolean` | Whether the caller asked for `cell-tris`, which the merge then builds locally. Every surface run keeps its layout capture for the outline; this flag only asks for the triangles. |
| <a id="areasubmissionplan-plannedjobcount"></a> `plannedJobCount?` | `readonly` | `number` | The number of jobs the run will submit. It equals the tile count on a grid run but can be larger on a facade run, where a tile can split into several separately billed jobs. When absent, use `entries.length`. |
| <a id="areasubmissionplan-polygon"></a> `polygon` | `readonly` | [`Polygon`](tiling.md#polygon) | The area the run covers. |
| <a id="areasubmissionplan-retrycontext"></a> `retryContext?` | `readonly` | `AreaRetryContext` | Present only when the run continues an earlier one with `retryFrom`. |
| <a id="areasubmissionplan-runid"></a> `runId` | `readonly` | `string` | Identifies the run; each job's idempotency key is derived from it, and the schedule keeps it. |
| <a id="areasubmissionplan-siteidentity"></a> `siteIdentity?` | `readonly` | `string` | Digest of the site inputs; a resumed run checks it before it resubmits paid jobs. |
| <a id="areasubmissionplan-surfacefields"></a> `surfaceFields` | `readonly` | `boolean` | Whether the analysis returns per-surface fields rather than a grid. |
| <a id="areasubmissionplan-terraincontextmarginm"></a> `terrainContextMarginM` | `readonly` | `number` | - |
| <a id="areasubmissionplan-tilepositions"></a> `tilePositions` | `readonly` | readonly [`TilePosition`](run-an-analysis.md#tileposition)\[\] | Where each tile sits in the grid. |
| <a id="areasubmissionplan-weatheridentity"></a> `weatherIdentity?` | `readonly` | `string` | The weather this plan's payloads were built from, if it is provable. |

***

<a id="checkareastate"></a>

## checkAreaState

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

> **checkAreaState**(`service`, `schedule`, `options?`): `Promise`&lt;[`AreaState`](run-an-analysis.md#areastate)&gt;

Poll every open job of a schedule once and return the resulting progress.

Status is read in batches of up to 50 jobs where the service supports it, and per job
otherwise. Each job record is updated in place. A job whose status request keeps failing is
marked `"skipped"` after repeated failures; a rate limit or temporary server error is never
counted against a job.

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `service` | [`AreaStatusService`](run-an-analysis.md#areastatusservice) | Reads job status, for example `client.jobs`. |
| `schedule` | `Pick`&lt;[`AreaSchedule`](run-an-analysis.md#areaschedule), `"jobs"`&gt; | The schedule to poll. Only its `jobs` are read. |
| `options` | [`CheckAreaStateOptions`](run-an-analysis.md#checkareastateoptions) | Concurrency, cancellation and a progress callback. |

### Returns

`Promise`&lt;[`AreaState`](run-an-analysis.md#areastate)&gt;

The counts of completed, failed, skipped, pending and running jobs.

### Throws

when `options.maxWorkers` is not a positive whole number.

### Throws

when `options.signal` is aborted; the abort reason is thrown.

***

<a id="checkareastateoptions"></a>

## CheckAreaStateOptions

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

Options for `checkAreaState`.

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="checkareastateoptions-maxworkers"></a> `maxWorkers?` | `readonly` | `number` | The most status requests in parallel. A positive whole number; default 5. |
| <a id="checkareastateoptions-onprogress"></a> `onProgress?` | `readonly` | (`state`) => `void` | Called with the run's counts once the check has read every job. |
| <a id="checkareastateoptions-signal"></a> `signal?` | `readonly` | `AbortSignal` | Aborts the status check. |

***

<a id="computeareastate"></a>

## computeAreaState

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

> **computeAreaState**(`schedule`): [`AreaState`](run-an-analysis.md#areastate)

Counts the jobs of a schedule by status; `isComplete` is true when none is pending or running.

### Parameters

| Parameter | Type |
| ------ | ------ |
| `schedule` | `Pick`&lt;[`AreaSchedule`](run-an-analysis.md#areaschedule), `"jobs"`&gt; |

### Returns

[`AreaState`](run-an-analysis.md#areastate)

***

<a id="freepreparedsites"></a>

## freePreparedSites

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

> **freePreparedSites**(): `number`

Release every prepared site this realm holds; returns how many it held.

A long-lived process that has finished with a site can drop tens of
megabytes here instead of waiting for the byte bound to evict them. The
next `runArea` on that site prepares it again.

### Returns

`number`

The number of sites that were held.

***

<a id="freezeareaschedule"></a>

## freezeAreaSchedule

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

> **freezeAreaSchedule**(`schedule`): [`AreaSchedule`](run-an-analysis.md#areaschedule)

Returns a frozen copy of a schedule; its lists, polygon and job map cannot be changed.

### Parameters

| Parameter | Type |
| ------ | ------ |
| `schedule` | [`AreaSchedule`](run-an-analysis.md#areaschedule) |

### Returns

[`AreaSchedule`](run-an-analysis.md#areaschedule)

***

<a id="job"></a>

## Job

Import from `@infrared-city/infrared-sdk-ts`.

A submitted analysis job, as reported by the service.

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="job-binary"></a> `binary?` | `readonly` | [`BinaryAcknowledgement`](requests.md#binaryacknowledgement) | The service's acknowledgement, when the job was submitted over the binary transport. |
| <a id="job-error"></a> `error?` | `readonly` | `string` | The failure message, when the job failed. |
| <a id="job-finishedat"></a> `finishedAt?` | `readonly` | `string` | When the job finished, when reported. |
| <a id="job-jobid"></a> `jobId` | `readonly` | `string` | The job's unique id. |
| <a id="job-modelname"></a> `modelName` | `readonly` | `string` | The analysis the job runs; an empty string when the service did not report it. |
| <a id="job-requestedat"></a> `requestedAt` | `readonly` | `string` | When the job was requested, as reported by the service; empty when not reported. |
| <a id="job-resultsurl"></a> `resultsUrl?` | `readonly` | `string` | Link to download the results from, when the service reports one. |
| <a id="job-startedat"></a> `startedAt?` | `readonly` | `string` | When the job started running, when reported. |
| <a id="job-status"></a> `status` | `readonly` | [`JobStatus`](run-an-analysis.md#jobstatus) | Current status of the job. |

***

<a id="jobsservice"></a>

## JobsService

Import from `@infrared-city/infrared-sdk-ts`.

Submits analysis jobs, reads their status and downloads their results;
available as `InfraredClient.jobs`.

### Constructors

<a id="jobsservice-constructor"></a>

#### Constructor

> **new JobsService**(`options`): `JobsService`

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`JobsServiceOptions`](client.md#jobsserviceoptions) | Base URL, credentials and transport settings. |

##### Returns

`JobsService`

##### Throws

when no `fetch` is available or `bigPayloadThresholdBytes` is invalid.

### Properties

<a id="jobsservice-captures"></a>

#### captures

> `readonly` **captures**: [`FacadeCaptures`](facade-layout.md#facadecaptures)

This client's facade captures, in one capture store. They live only as long as the
client: nothing is written to disk and nothing is saved in an `AreaSchedule`. The client has
no `dispose`: call `captures.free()` when you are done with it.

### Accessors

<a id="jobsservice-batchedstatussupported"></a>

#### batchedStatusSupported

##### Get Signature

> **get** **batchedStatusSupported**(): `boolean`

Whether the API's route for reading many job statuses at once has
answered this client. `false` until it has, and for good once the API
shows it lacks the route; area runs use it to choose their poll interval.

###### Returns

`boolean`

### Methods

<a id="jobsservice-binarycapability"></a>

#### binaryCapability()

> **binaryCapability**(`signal?`): `Promise`&lt;[`BinaryCapability`](requests.md#binarycapability)&gt;

The API's live capability document, which says whether a model's binary
route is available. It is cached for a short time, so repeated calls are
cheap.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `signal?` | `AbortSignal` |

##### Returns

`Promise`&lt;[`BinaryCapability`](requests.md#binarycapability)&gt;

***

<a id="jobsservice-decompress"></a>

#### decompress()

> **decompress**(`content`, `options?`): [`ParsedResult`](results-and-legend.md#parsedresult)

Unpacks a downloaded result archive and returns the parsed result.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `content` | `Uint8Array` |
| `options?` | [`ParseResultOptions`](results-and-legend.md#parseresultoptions) |

##### Returns

[`ParsedResult`](results-and-legend.md#parsedresult)

***

<a id="jobsservice-downloadresults"></a>

#### downloadResults()

> **downloadResults**(`jobId`, `options?`): `Promise`&lt;[`DownloadResult`](results-and-legend.md#downloadresult)&gt;

Downloads the result archive of a finished job, retrying a failed
download a few times. Pass `options.job` to skip reading the status.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `jobId` | `string` |
| `options` | [`DownloadResultsOptions`](requests.md#downloadresultsoptions) |

##### Returns

`Promise`&lt;[`DownloadResult`](results-and-legend.md#downloadresult)&gt;

##### Throws

when the job has not succeeded.

##### Throws

when `options.job` is a different job.

***

<a id="jobsservice-getstatus"></a>

#### getStatus()

> **getStatus**(`jobId`, `options?`): `Promise`&lt;[`Job`](run-an-analysis.md#job)&gt;

Reads one job's status.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `jobId` | `string` |
| `options` | \{ `signal?`: `AbortSignal`; \} |
| `options.signal?` | `AbortSignal` |

##### Returns

`Promise`&lt;[`Job`](run-an-analysis.md#job)&gt;

***

<a id="jobsservice-getstatusbatch"></a>

#### getStatusBatch()

> **getStatusBatch**(`jobIds`, `options?`): `Promise`&lt;[`StatusSweep`](run-an-analysis.md#statussweep)&gt;

Reads many job statuses at once, 50 ids per request. Ids it could not
settle come back in `unanswered` for you to ask about one by one; it does
not throw because of an API problem. An API without the route is asked
once and never again.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `jobIds` | readonly `string`\[\] |
| `options` | \{ `maxWorkers?`: `number`; `signal?`: `AbortSignal`; \} |
| `options.maxWorkers?` | `number` |
| `options.signal?` | `AbortSignal` |

##### Returns

`Promise`&lt;[`StatusSweep`](run-an-analysis.md#statussweep)&gt;

***

<a id="jobsservice-preflightprepared"></a>

#### preflightPrepared()

> **preflightPrepared**(`prepared`, `options?`): `Promise`&lt;`void`&gt;

Finishes all validation and encoding of a binary submission before any
paid request is sent. The encoded bytes are kept (within a memory budget)
and `submitPrepared` sends exactly those bytes. If you pre-check a whole
plan and then do not submit part of it, call `releasePreflight` for the
rest.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `prepared` | [`PreparedSubmission`](run-an-analysis.md#preparedsubmission) |
| `options` | \{ `retain?`: `boolean`; `signal?`: `AbortSignal`; \} |
| `options.retain?` | `boolean` |
| `options.signal?` | `AbortSignal` |

##### Returns

`Promise`&lt;`void`&gt;

***

<a id="jobsservice-preparesubmission"></a>

#### prepareSubmission()

> **prepareSubmission**(`analysisType`, `payload`, `options?`): [`PreparedSubmission`](run-an-analysis.md#preparedsubmission)

Validates and encodes a request without sending it; returns the `PreparedSubmission`.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `analysisType` | `string` |
| `payload` | `Readonly`&lt;`Record`&lt;`string`, `unknown`&gt;&gt; |
| `options` | `Omit`&lt;[`SubmitOptions`](requests.md#submitoptions), `"signal"`&gt; |

##### Returns

[`PreparedSubmission`](run-an-analysis.md#preparedsubmission)

***

<a id="jobsservice-releasepreflight"></a>

#### releasePreflight()

> **releasePreflight**(`prepared`): `void`

Frees what `preflightPrepared` is holding for a submission that will not happen.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `prepared` | [`PreparedSubmission`](run-an-analysis.md#preparedsubmission) |

##### Returns

`void`

***

<a id="jobsservice-submit"></a>

#### submit()

> **submit**(`analysisType`, `payload`, `options?`): `Promise`&lt;[`Job`](run-an-analysis.md#job)&gt;

Prepares and sends one analysis request; returns the accepted `Job`
without waiting for it. The request is sent as binary unless
`options.transport` is `"json"` or the analysis has no binary route.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `analysisType` | `string` |
| `payload` | `Readonly`&lt;`Record`&lt;`string`, `unknown`&gt;&gt; |
| `options` | [`SubmitOptions`](requests.md#submitoptions) |

##### Returns

`Promise`&lt;[`Job`](run-an-analysis.md#job)&gt;

***

<a id="jobsservice-submitprepared"></a>

#### submitPrepared()

> **submitPrepared**(`prepared`, `options?`): `Promise`&lt;[`Job`](run-an-analysis.md#job)&gt;

Sends a `PreparedSubmission` and returns the accepted `Job`; the options are used by area runs.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `prepared` | [`PreparedSubmission`](run-an-analysis.md#preparedsubmission) | - |
| `options` | \{ `beforeDispatch?`: () => `void`; `idempotencyKey?`: `string`; `signal?`: `AbortSignal`; `stages?`: \{ `post`: &lt;`T`&gt;(`send`) => `Promise`&lt;`T`&gt;; `uploaded`: () => `void`; \}; \} | - |
| `options.beforeDispatch?` | () => `void` | - |
| `options.idempotencyKey?` | `string` | The `Idempotency-Key` that makes a retried send safe; unset for a single submit. |
| `options.signal?` | `AbortSignal` | - |
| `options.stages?` | \{ `post`: &lt;`T`&gt;(`send`) => `Promise`&lt;`T`&gt;; `uploaded`: () => `void`; \} | The upload and POST slots of one area run; unset for a single submit. |
| `options.stages.post` | &lt;`T`&gt;(`send`) => `Promise`&lt;`T`&gt; | - |
| `options.stages.uploaded` | () => `void` | - |

##### Returns

`Promise`&lt;[`Job`](run-an-analysis.md#job)&gt;

***

<a id="jobsservice-waitforcompletion"></a>

#### waitForCompletion()

> **waitForCompletion**(`jobId`, `options?`): `Promise`&lt;[`Job`](run-an-analysis.md#job)&gt;

Polls a job until it succeeds or fails. `options.timeout` is in seconds
(default 900).

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `jobId` | `string` |
| `options` | [`WaitForCompletionOptions`](requests.md#waitforcompletionoptions) |

##### Returns

`Promise`&lt;[`Job`](run-an-analysis.md#job)&gt;

The finished `Job`.

##### Throws

when the job fails.

##### Throws

when the timeout passes first.

##### Throws

when `options.signal` aborts the wait.

***

<a id="jobstatus"></a>

## JobStatus

Import from `@infrared-city/infrared-sdk-ts`.

> **JobStatus** = *typeof* [`JobStatus`](run-an-analysis.md#jobstatus)\[keyof *typeof* [`JobStatus`](run-an-analysis.md#jobstatus)\]

One of the `JobStatus` values: `"pending"`, `"running"`, `"succeeded"`,
`"failed"` or `"unknown"`.


> `const` **JobStatus**: `object`

The states a job can be in: `pending`, `running`, `succeeded`, `failed`, or
`unknown` when the service reports a status the SDK does not recognise.

### Type Declaration

| Name | Type | Default value |
| ------ | ------ | ------ |
| <a id="jobstatus-failed"></a> `Failed` | `"failed"` | `"failed"` |
| <a id="jobstatus-pending"></a> `Pending` | `"pending"` | `"pending"` |
| <a id="jobstatus-running"></a> `Running` | `"running"` | `"running"` |
| <a id="jobstatus-succeeded"></a> `Succeeded` | `"succeeded"` | `"succeeded"` |
| <a id="jobstatus-unknown"></a> `Unknown` | `"unknown"` | `"unknown"` |

***

<a id="kernelpart"></a>

## KernelPart

Import from `@infrared-city/infrared-sdk-ts`.

One part of a parts plan: a job that covers some of the request's floors.

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="kernelpart-floor_keys"></a> `floor_keys` | `readonly` | readonly `string`\[\] | Keys of the floors the part covers. |
| <a id="kernelpart-floors"></a> `floors` | `readonly` | readonly `unknown`\[\] \| `null` | The part's `floors` selectors; `null` for a request sent as one part. |
| <a id="kernelpart-key"></a> `key` | `readonly` | `string` | Key of the part, unique within the plan. |
| <a id="kernelpart-sensors"></a> `sensors` | `readonly` | `number` | Number of sensors in the part. |

***

<a id="kernelpartsplan"></a>

## KernelPartsPlan

Import from `@infrared-city/infrared-sdk-ts`.

The plan that splits a daylight-factor request into parts, parsed.

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="kernelpartsplan-notes"></a> `notes` | `readonly` | readonly `string`\[\] | Notes on inputs the analysis accepts silently. |
| <a id="kernelpartsplan-parts"></a> `parts` | `readonly` | readonly [`KernelPart`](run-an-analysis.md#kernelpart)\[\] | The parts, in plan order. |
| <a id="kernelpartsplan-target"></a> `target` | `readonly` | `number` | The target the plan was made for. |
| <a id="kernelpartsplan-tier"></a> `tier` | `readonly` | `string` | The request tier the plan was made for, for example `"floors"` or `"buildings"`. |
| <a id="kernelpartsplan-total_sensors"></a> `total_sensors` | `readonly` | `number` | Sensors of the whole request. |
| <a id="kernelpartsplan-unsplit_reason"></a> `unsplit_reason` | `readonly` | `string` \| `null` | Why the request was sent as one part, when it was; otherwise `null`. |

***

<a id="mergeareajobs"></a>

## mergeAreaJobs

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

> **mergeAreaJobs**(`jobsService`, `schedule`, `options?`): `Promise`&lt;[`AreaResult`](results-and-legend.md#arearesult)&gt;

Poll a grid schedule once, download the results of its completed tiles and merge them into
one grid.

Calling it again after a failure gives tiles that were retired by repeated status errors one
more chance, since their jobs usually finished.

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `jobsService` | [`AreaMergeJobsService`](run-an-analysis.md#areamergejobsservice) | Reads job status and downloads results, for example `client.jobs`. |
| `schedule` | [`AreaSchedule`](run-an-analysis.md#areaschedule) | The schedule returned by `runArea`. |
| `options` | [`AreaMergeOptions`](run-an-analysis.md#areamergeoptions) | Blend strategy, concurrency, cancellation and logging. |

### Returns

`Promise`&lt;[`AreaResult`](results-and-legend.md#arearesult)&gt;

The merged grid with its shape, legend range and any failed or skipped tiles.

### Throws

when the schedule is a facade or surface schedule, contains an uncertain
or invalid geometry reference, or `options` ask for a directional strategy on a
non-wind analysis or without `windDirectionDeg`.

### Throws

when any tile failed, was skipped or could not be downloaded.

***

<a id="mergepartsoptions"></a>

## MergePartsOptions

Import from `@infrared-city/infrared-sdk-ts`.

Options for joining the results of a parts run.

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="mergepartsoptions-logger"></a> `logger?` | `readonly` | [`Logger`](client.md#logger) | Where a JSON fallback of the join is logged. |
| <a id="mergepartsoptions-maxworkers"></a> `maxWorkers?` | `readonly` | `number` | Width of the download pool. |
| <a id="mergepartsoptions-resultformat"></a> `resultFormat?` | `readonly` | [`DaylightResultFormat`](results-and-legend.md#daylightresultformat) | As `PartsOptions.resultFormat`. Unset: `DEFAULT_DAYLIGHT_RESULT_FORMAT`. |
| <a id="mergepartsoptions-signal"></a> `signal?` | `readonly` | `AbortSignal` | Aborts the polling and the downloads. |

***

<a id="mergesurfaceareajobs"></a>

## mergeSurfaceAreaJobs

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

> **mergeSurfaceAreaJobs**(`jobsService`, `schedule`, `options?`): `Promise`&lt;[`SurfaceColumns`](results-and-legend.md#surfacecolumns)&gt;

Polls a surface schedule once, downloads the results of all its jobs and joins them into
one set of surface columns.

Every job must have completed: any failed or missing submission, or any job still pending or
running, makes the merge fail instead of returning a partial result. Calling it again after
a failure gives tiles that were retired by repeated status errors one more chance. A schedule
with no jobs gives empty columns.

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `jobsService` | [`AreaMergeJobsService`](run-an-analysis.md#areamergejobsservice) | Reads job status and downloads results, for example `client.jobs`. |
| `schedule` | [`AreaSchedule`](run-an-analysis.md#areaschedule) | The schedule returned by `runArea` for a surface analysis. |
| `options` | `Pick`&lt;[`AreaMergeOptions`](run-an-analysis.md#areamergeoptions), `"maxWorkers"` \| `"signal"` \| `"logger"`&gt; | `maxWorkers` (concurrent downloads), `signal` (cancellation) and `logger`. |

### Returns

`Promise`&lt;[`SurfaceColumns`](results-and-legend.md#surfacecolumns)&gt;

The merged surface columns.

### Throws

when the schedule is not a surface schedule, contains an uncertain or invalid
  geometry reference, has failed or uncertain submissions, has jobs that did not succeed, or a
  download or decode failed (the cause is attached).

### Throws

when `options.signal` is aborted: the abort reason.

***

<a id="partsoptions"></a>

## PartsOptions

Import from `@infrared-city/infrared-sdk-ts`.

Options for submitting a request as parts.

### Extended by

- [`PartsWaitOptions`](run-an-analysis.md#partswaitoptions)

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="partsoptions-maxparts"></a> `maxParts?` | `readonly` | `number` | The most jobs the run may submit. `1` turns splitting off: the request is sent as one job, exactly as `analyses.execute` sends it. A plan with more parts than a larger value is refused before any request. Default: no limit. |
| <a id="partsoptions-maxworkers"></a> `maxWorkers?` | `readonly` | `number` | Width of the submit and download pools (default 8). |
| <a id="partsoptions-onaccepted"></a> `onAccepted?` | `readonly` | (`jobId`, `partKey`) => `void` | Called with the job id and part key of each part the server accepts. An observer only: use it to store job ids before the run returns. |
| <a id="partsoptions-onprogress"></a> `onProgress?` | `readonly` | (`state`) => `void` | Called with the progress of the run each time the parts are polled. |
| <a id="partsoptions-resultformat"></a> `resultFormat?` | `readonly` | [`DaylightResultFormat`](results-and-legend.md#daylightresultformat) | The format of a daylight-factor result. `"irbf"`: a `DaylightFactorResult` (typed-array views, with `toJson()` on demand); parts ask the server for binary results when it offers them, else JSON, which is converted into the same frame. `"json"`: the JSON value. Unset: `DEFAULT_DAYLIGHT_RESULT_FORMAT`. Other analyses ignore it. |
| <a id="partsoptions-retryfrom"></a> `retryFrom?` | `readonly` | [`PartsSchedule`](run-an-analysis.md#partsschedule) | A schedule from an earlier run of the same request (its `requestDigest` must match). Only the parts that failed (a failed submission or a failed job) are sent again; a part whose submission outcome is unknown never is. |
| <a id="partsoptions-signal"></a> `signal?` | `readonly` | `AbortSignal` | Aborts the run. |
| <a id="partsoptions-transport"></a> `transport?` | `readonly` | `"json"` \| `"binary"` | How the parts are sent, as for `analyses.execute`. Unset (the default) picks the route automatically from what the server supports: the binary route, where the scene is uploaded once, or JSON. `"json"` keeps every part on JSON; `"binary"` sends the request as a single job and never splits it. |
| <a id="partsoptions-webhookevents"></a> `webhookEvents?` | `readonly` | readonly `string`\[\] | The job events that trigger `webhookUrl`. |
| <a id="partsoptions-webhookurl"></a> `webhookUrl?` | `readonly` | `string` | A URL the API calls when a job reaches one of `webhookEvents`. |

***

<a id="partspreview"></a>

## PartsPreview

Import from `@infrared-city/infrared-sdk-ts`.

The offline answer of `previewParts`: what a run would submit and bill.

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="partspreview-analysistype"></a> `analysisType` | `readonly` | `string` | The analysis type of the request. |
| <a id="partspreview-estimatedcosttokens"></a> `estimatedCostTokens` | `readonly` | `number` | Estimated cost of the run in tokens: `partCount` times `tokensPerJob`. |
| <a id="partspreview-notes"></a> `notes` | `readonly` | readonly `string`\[\] | Notes on inputs the analysis accepts silently. |
| <a id="partspreview-partcount"></a> `partCount` | `readonly` | `number` | Jobs the run submits: 1 when the request does not split. |
| <a id="partspreview-parts"></a> `parts` | `readonly` | readonly `object`\[\] | The parts of the plan; empty when the request is not planned into parts. |
| <a id="partspreview-tokensperjob"></a> `tokensPerJob` | `readonly` | `number` | Tokens billed per job. |
| <a id="partspreview-totalsensors"></a> `totalSensors` | `readonly` | `number` | Exact sensors of the request (the worker's own grid); 0 when not planned. |
| <a id="partspreview-unsplitreason"></a> `unsplitReason?` | `readonly` | `string` | Why the request is sent as one part, when it is. |

***

<a id="partsschedule"></a>

## PartsSchedule

Import from `@infrared-city/infrared-sdk-ts`.

A submitted parts run.

Like an `AreaSchedule`, its job records are updated in place while the run is polled.
Keep it to merge the run later or to retry the failed parts.

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="partsschedule-analysistype"></a> `analysisType` | `readonly` | `string` | The analysis type of the run. |
| <a id="partsschedule-failedsubmissions"></a> `failedSubmissions` | `readonly` | readonly `string`\[\] | Parts whose submission failed. |
| <a id="partsschedule-jobs"></a> `jobs` | `readonly` | `ReadonlyMap`&lt;`string`, [`AreaJob`](run-an-analysis.md#areajob)&gt; | The job of each part, by part key. |
| <a id="partsschedule-partkeys"></a> `partKeys` | `readonly` | readonly `string`\[\] | Part keys, in plan order. |
| <a id="partsschedule-plan"></a> `plan` | `readonly` | `string` | The plan of the run, as text. Merging reads it. |
| <a id="partsschedule-requestdigest"></a> `requestDigest?` | `readonly` | `string` | `sha256:` digest of the request's JSON bytes; a `retryFrom` must match it. Absent when the runtime has no SHA-256; such a schedule cannot be retried. |
| <a id="partsschedule-resultformat"></a> `resultFormat?` | `readonly` | [`DaylightResultFormat`](results-and-legend.md#daylightresultformat) | The daylight-factor result format the run chose. `mergeParts` uses it when the caller names none. Absent on an older schedule. |
| <a id="partsschedule-submissionabortstatus"></a> `submissionAbortStatus` | `readonly` | `number` \| `null` | HTTP status that stopped the submission early, or `null` when it was not stopped. |
| <a id="partsschedule-uncertainsubmissions"></a> `uncertainSubmissions` | `readonly` | readonly `string`\[\] | Parts whose submission may have been accepted. Never resubmitted automatically. |

***

<a id="partswaitoptions"></a>

## PartsWaitOptions

Import from `@infrared-city/infrared-sdk-ts`.

Options for running parts and waiting for them to finish.

### Extends

- [`PartsOptions`](run-an-analysis.md#partsoptions)

### Extended by

- [`RunAndWaitOptions`](run-an-analysis.md#runandwaitoptions)

### Properties

| Property | Modifier | Type | Description | Inherited from |
| ------ | ------ | ------ | ------ | ------ |
| <a id="partswaitoptions-maxparts"></a> `maxParts?` | `readonly` | `number` | The most jobs the run may submit. `1` turns splitting off: the request is sent as one job, exactly as `analyses.execute` sends it. A plan with more parts than a larger value is refused before any request. Default: no limit. | [`PartsOptions`](run-an-analysis.md#partsoptions).[`maxParts`](run-an-analysis.md#partsoptions-maxparts) |
| <a id="partswaitoptions-maxworkers"></a> `maxWorkers?` | `readonly` | `number` | Width of the submit and download pools (default 8). | [`PartsOptions`](run-an-analysis.md#partsoptions).[`maxWorkers`](run-an-analysis.md#partsoptions-maxworkers) |
| <a id="partswaitoptions-onaccepted"></a> `onAccepted?` | `readonly` | (`jobId`, `partKey`) => `void` | Called with the job id and part key of each part the server accepts. An observer only: use it to store job ids before the run returns. | [`PartsOptions`](run-an-analysis.md#partsoptions).[`onAccepted`](run-an-analysis.md#partsoptions-onaccepted) |
| <a id="partswaitoptions-onprogress"></a> `onProgress?` | `readonly` | (`state`) => `void` | Called with the progress of the run each time the parts are polled. | [`PartsOptions`](run-an-analysis.md#partsoptions).[`onProgress`](run-an-analysis.md#partsoptions-onprogress) |
| <a id="partswaitoptions-resultformat"></a> `resultFormat?` | `readonly` | [`DaylightResultFormat`](results-and-legend.md#daylightresultformat) | The format of a daylight-factor result. `"irbf"`: a `DaylightFactorResult` (typed-array views, with `toJson()` on demand); parts ask the server for binary results when it offers them, else JSON, which is converted into the same frame. `"json"`: the JSON value. Unset: `DEFAULT_DAYLIGHT_RESULT_FORMAT`. Other analyses ignore it. | [`PartsOptions`](run-an-analysis.md#partsoptions).[`resultFormat`](run-an-analysis.md#partsoptions-resultformat) |
| <a id="partswaitoptions-retryfrom"></a> `retryFrom?` | `readonly` | [`PartsSchedule`](run-an-analysis.md#partsschedule) | A schedule from an earlier run of the same request (its `requestDigest` must match). Only the parts that failed (a failed submission or a failed job) are sent again; a part whose submission outcome is unknown never is. | [`PartsOptions`](run-an-analysis.md#partsoptions).[`retryFrom`](run-an-analysis.md#partsoptions-retryfrom) |
| <a id="partswaitoptions-signal"></a> `signal?` | `readonly` | `AbortSignal` | Aborts the run. | [`PartsOptions`](run-an-analysis.md#partsoptions).[`signal`](run-an-analysis.md#partsoptions-signal) |
| <a id="partswaitoptions-timeout"></a> `timeout?` | `readonly` | `number` | Seconds to wait for every part. Default 900, the same as for one job. Checked before any request is sent. | - |
| <a id="partswaitoptions-transport"></a> `transport?` | `readonly` | `"json"` \| `"binary"` | How the parts are sent, as for `analyses.execute`. Unset (the default) picks the route automatically from what the server supports: the binary route, where the scene is uploaded once, or JSON. `"json"` keeps every part on JSON; `"binary"` sends the request as a single job and never splits it. | [`PartsOptions`](run-an-analysis.md#partsoptions).[`transport`](run-an-analysis.md#partsoptions-transport) |
| <a id="partswaitoptions-webhookevents"></a> `webhookEvents?` | `readonly` | readonly `string`\[\] | The job events that trigger `webhookUrl`. | [`PartsOptions`](run-an-analysis.md#partsoptions).[`webhookEvents`](run-an-analysis.md#partsoptions-webhookevents) |
| <a id="partswaitoptions-webhookurl"></a> `webhookUrl?` | `readonly` | `string` | A URL the API calls when a job reaches one of `webhookEvents`. | [`PartsOptions`](run-an-analysis.md#partsoptions).[`webhookUrl`](run-an-analysis.md#partsoptions-webhookurl) |

***

<a id="prepareanalysispayload"></a>

## prepareAnalysisPayload

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

> **prepareAnalysisPayload**(`input`): `Record`&lt;`string`, `unknown`&gt;

Turns an analysis input into the request body for one analysis, with wire field names.
Entity and metadata maps pass through unchanged.

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `input` | `Readonly`&lt;`Record`&lt;`string`, `unknown`&gt;&gt; | The analysis input, with `analysisType` (or the wire key `analysis-type`). |

### Returns

`Record`&lt;`string`, `unknown`&gt;

The request body.

### Throws

when the input is invalid for its analysis type.

***

<a id="prepareareapayload"></a>

## prepareAreaPayload

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

> `const` **prepareAreaPayload**: (`input`) => `Record`&lt;`string`, `unknown`&gt; = `prepareAnalysisPayload`

Alias of `prepareAnalysisPayload`.

Turns an analysis input into the request body for one analysis, with wire field names.
Entity and metadata maps pass through unchanged.

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `input` | `Readonly`&lt;`Record`&lt;`string`, `unknown`&gt;&gt; | The analysis input, with `analysisType` (or the wire key `analysis-type`). |

### Returns

`Record`&lt;`string`, `unknown`&gt;

The request body.

### Throws

when the input is invalid for its analysis type.

***

<a id="preparedsubmission"></a>

## PreparedSubmission

Import from `@infrared-city/infrared-sdk-ts`.

A validated, mesh-packed request body that is ready to be submitted.

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="preparedsubmission-analysistype"></a> `analysisType` | `readonly` | `string` | The analysis the body is for, e.g. `"wind-speed"`. |
| <a id="preparedsubmission-artifact"></a> `artifact?` | `readonly` | (`limits`) => `UploadArtifact` | Builds the tile's binary upload, for a body that an area plan produced. A direct submission has none. |
| <a id="preparedsubmission-body"></a> `body` | `readonly` | `Readonly`&lt;`Record`&lt;`string`, `unknown`&gt;&gt; | The request body that will be sent. |
| <a id="preparedsubmission-interiorbinary"></a> `interiorBinary?` | `readonly` | `PreparedBinary` | A prepared binary upload for one part of an interior (daylight-factor) analysis. Absent on every other submission. |
| <a id="preparedsubmission-interiorresultformat"></a> `interiorResultFormat?` | `readonly` | `"irbf"` \| `"json"` | The result format an interior binary part asks for; unset means `"json"`. |
| <a id="preparedsubmission-json"></a> `json?` | `readonly` | () => `Uint8Array` | The exact JSON bytes of `body`, when they were already written once. The JSON route sends these bytes instead of serializing `body` again. A direct submission has none. |
| <a id="preparedsubmission-reusescope"></a> `reuseScope?` | `readonly` | `string` | Scope under which compatible geometry from earlier submissions can be reused. |
| <a id="preparedsubmission-transport"></a> `transport` | `readonly` | `"json"` \| `"binary"` | How the body is sent: as JSON or as a compact binary upload. |

***

<a id="preparedweatheridentity"></a>

## preparedWeatherIdentity

Import from `@infrared-city/infrared-sdk-ts`.

> **preparedWeatherIdentity**(`payload`): `string`

The weather identity of a prepared payload: the value `runArea` records on the schedule,
computed without submitting anything.

Pass the output of `prepareAnalysisPayload` or `prepareAreaPayload`, not a `runArea` input.
The prepared payload holds the weather arrays whichever source produced them: a parsed file,
the public catalog's records or your own arrays.

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `payload` | `Readonly`&lt;`Record`&lt;`string`, `unknown`&gt;&gt; | A prepared analysis payload. |

### Returns

`string`

The identity string of the weather the payload submits.

### Throws

when the payload carries no location, no time window or no
weather column.

***

<a id="previewareabatches"></a>

## previewAreaBatches

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

> **previewAreaBatches**(`service`, `input`, `polygon`, `options?`): `Promise`&lt;[`AreaBatchPreview`](run-an-analysis.md#areabatchpreview)&gt;

Preview the jobs a `runArea(service, input, polygon, options)` call would submit, without
submitting anything.

It reports the real number of jobs, which on a facade (`analysisSurfaces`) request can exceed
the tile count because a tile may split into several billed batches. On a grid request it
gives one job per tile, like `previewArea`. Most callers want
`client.previewAreaBatches(input, polygon, options)`, which passes `client.jobs` as `service`.

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `service` | [`AreaJobsService`](run-an-analysis.md#areajobsservice) | The jobs service the plan is prepared against, for example `client.jobs`. |
| `input` | [`RunAreaInputLike`](run-an-analysis.md#runareainputlike) | The analysis request fields. |
| `polygon` | [`Polygon`](tiling.md#polygon) | The area to analyse. |
| `options` | [`RunAreaOptions`](run-an-analysis.md#runareaoptions) | The same run options `runArea` takes. |

### Returns

`Promise`&lt;[`AreaBatchPreview`](run-an-analysis.md#areabatchpreview)&gt;

The tile count, planned job count, estimated time and cost, and the sensor count for
a facade request.

***

<a id="runandwaitoptions"></a>

## RunAndWaitOptions

Import from `@infrared-city/infrared-sdk-ts`.

Options for running an analysis and waiting for its result, when the request may be
split into parts.

### Extends

- [`PartsWaitOptions`](run-an-analysis.md#partswaitoptions)

### Properties

| Property | Modifier | Type | Description | Inherited from |
| ------ | ------ | ------ | ------ | ------ |
| <a id="runandwaitoptions-archive"></a> `archive?` | `readonly` | [`DecompressResultArchiveOptions`](results-and-legend.md#decompressresultarchiveoptions) | Size limits for the downloaded result archive (as `jobs.decompress`), for every analysis. | - |
| <a id="runandwaitoptions-maxparts"></a> `maxParts?` | `readonly` | `number` | The most jobs the run may submit. `1` turns splitting off: the request is sent as one job, exactly as `analyses.execute` sends it. A plan with more parts than a larger value is refused before any request. Default: no limit. | [`PartsWaitOptions`](run-an-analysis.md#partswaitoptions).[`maxParts`](run-an-analysis.md#partswaitoptions-maxparts) |
| <a id="runandwaitoptions-maxworkers"></a> `maxWorkers?` | `readonly` | `number` | Width of the submit and download pools (default 8). | [`PartsWaitOptions`](run-an-analysis.md#partswaitoptions).[`maxWorkers`](run-an-analysis.md#partswaitoptions-maxworkers) |
| <a id="runandwaitoptions-onaccepted"></a> `onAccepted?` | `readonly` | (`jobId`, `partKey`) => `void` | Called with the job id and part key of each part the server accepts. An observer only: use it to store job ids before the run returns. | [`PartsWaitOptions`](run-an-analysis.md#partswaitoptions).[`onAccepted`](run-an-analysis.md#partswaitoptions-onaccepted) |
| <a id="runandwaitoptions-onpoll"></a> `onPoll?` | `readonly` | [`OnPollCallback`](requests.md#onpollcallback) | Called with one job's status after each poll. Not called for a multi-part run, which polls all parts together: use `onProgress` there. | - |
| <a id="runandwaitoptions-onprogress"></a> `onProgress?` | `readonly` | (`state`) => `void` | Called with the progress of the run each time the parts are polled. | [`PartsWaitOptions`](run-an-analysis.md#partswaitoptions).[`onProgress`](run-an-analysis.md#partswaitoptions-onprogress) |
| <a id="runandwaitoptions-resultformat"></a> `resultFormat?` | `readonly` | [`DaylightResultFormat`](results-and-legend.md#daylightresultformat) | The format of a daylight-factor result. `"irbf"`: a `DaylightFactorResult` (typed-array views, with `toJson()` on demand); parts ask the server for binary results when it offers them, else JSON, which is converted into the same frame. `"json"`: the JSON value. Unset: `DEFAULT_DAYLIGHT_RESULT_FORMAT`. Other analyses ignore it. | [`PartsWaitOptions`](run-an-analysis.md#partswaitoptions).[`resultFormat`](run-an-analysis.md#partswaitoptions-resultformat) |
| <a id="runandwaitoptions-retryfrom"></a> `retryFrom?` | `readonly` | [`PartsSchedule`](run-an-analysis.md#partsschedule) | A schedule from an earlier run of the same request (its `requestDigest` must match). Only the parts that failed (a failed submission or a failed job) are sent again; a part whose submission outcome is unknown never is. | [`PartsWaitOptions`](run-an-analysis.md#partswaitoptions).[`retryFrom`](run-an-analysis.md#partswaitoptions-retryfrom) |
| <a id="runandwaitoptions-signal"></a> `signal?` | `readonly` | `AbortSignal` | Aborts the run. | [`PartsWaitOptions`](run-an-analysis.md#partswaitoptions).[`signal`](run-an-analysis.md#partswaitoptions-signal) |
| <a id="runandwaitoptions-timeout"></a> `timeout?` | `readonly` | `number` | Seconds to wait for every part. Default 900, the same as for one job. Checked before any request is sent. | [`PartsWaitOptions`](run-an-analysis.md#partswaitoptions).[`timeout`](run-an-analysis.md#partswaitoptions-timeout) |
| <a id="runandwaitoptions-transport"></a> `transport?` | `readonly` | `"json"` \| `"binary"` | How the parts are sent, as for `analyses.execute`. Unset (the default) picks the route automatically from what the server supports: the binary route, where the scene is uploaded once, or JSON. `"json"` keeps every part on JSON; `"binary"` sends the request as a single job and never splits it. | [`PartsWaitOptions`](run-an-analysis.md#partswaitoptions).[`transport`](run-an-analysis.md#partswaitoptions-transport) |
| <a id="runandwaitoptions-webhookevents"></a> `webhookEvents?` | `readonly` | readonly `string`\[\] | The job events that trigger `webhookUrl`. | [`PartsWaitOptions`](run-an-analysis.md#partswaitoptions).[`webhookEvents`](run-an-analysis.md#partswaitoptions-webhookevents) |
| <a id="runandwaitoptions-webhookurl"></a> `webhookUrl?` | `readonly` | `string` | A URL the API calls when a job reaches one of `webhookEvents`. | [`PartsWaitOptions`](run-an-analysis.md#partswaitoptions).[`webhookUrl`](run-an-analysis.md#partswaitoptions-webhookurl) |

***

<a id="runarea"></a>

## runArea

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

> **runArea**(`service`, `input`, `polygon`, `options?`): `Promise`&lt;[`AreaSchedule`](run-an-analysis.md#areaschedule)&gt;

Plans an area run for a polygon and submits it: tiles the polygon, builds each tile's request
and sends one job per tile (or per batch of facade sensors).

Returns as soon as the jobs are submitted; poll the jobs with `checkAreaState` and merge the
results with `mergeAreaJobs`, or use `InfraredClient.runAreaAndWait` to do all three. Every
tile is a billed job, so size the run first with `previewAreaBatches`.

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `service` | [`AreaJobsService`](run-an-analysis.md#areajobsservice) | The jobs service that sends the jobs, for example `client.jobs`. |
| `input` | [`RunAreaInput`](run-an-analysis.md#runareainput) | The analysis request: `analysisType` plus the analysis's own parameters. |
| `polygon` | [`Polygon`](tiling.md#polygon) | The GeoJSON `Polygon` to analyse. |
| `options` | [`RunAreaOptions`](run-an-analysis.md#runareaoptions) | The run options (see `RunAreaOptions`). |

### Returns

`Promise`&lt;[`AreaSchedule`](run-an-analysis.md#areaschedule)&gt;

The frozen schedule of the run, to poll, merge or save.

### Throws

when the unsupported `binaryResults` option is passed, or
  `terrainContextMarginM` is not a finite non-negative number.

### Throws

when `retryFrom` was saved with a different transport or terrain margin.

### Throws

when the API accepted a job with an invalid geometry
  reference.

***

<a id="runareaandwaitoptions"></a>

## RunAreaAndWaitOptions

Import from `@infrared-city/infrared-sdk-ts`.

Options for `InfraredClient.runAreaAndWait`: everything `runArea` takes,
plus the merge options.

### Extends

- [`RunAreaOptions`](run-an-analysis.md#runareaoptions).[`AreaMergeOptions`](run-an-analysis.md#areamergeoptions)

### Properties

| Property | Modifier | Type | Description | Inherited from |
| ------ | ------ | ------ | ------ | ------ |
| <a id="runareaandwaitoptions-areatimeout"></a> `areaTimeout?` | `readonly` | `number` | `runAreaAndWait` only: seconds to wait for the whole run before it throws `AreaTimeoutError`. A positive number; default 3600. | [`RunAreaOptions`](run-an-analysis.md#runareaoptions).[`areaTimeout`](run-an-analysis.md#runareaoptions-areatimeout) |
| <a id="runareaandwaitoptions-block"></a> `block?` | `readonly` | `number` | Largest block, in cells per side, that the directional strategies process at once; at least 1. It trades speed against memory only: the result is the same for any value. Default 928. | [`AreaMergeOptions`](run-an-analysis.md#areamergeoptions).[`block`](run-an-analysis.md#areamergeoptions-block) |
| <a id="runareaandwaitoptions-buildings"></a> `buildings?` | `readonly` | [`AreaBuildings`](buildings.md#areabuildings) \| `Readonly`&lt;`Record`&lt;`string`, `unknown`&gt;&gt; | The target buildings: an `AreaBuildings` from `BuildingsService.getBuildingsInArea`, or a bare `{buildingId: mesh}` map. An `AreaBuildings` carries `origin` — the frame its bodies are in — and the payload path re-anchors from that origin into this run's site frame, so buildings acquired once for a large area can be run as several sub-areas. A bare map carries no frame and is assumed to be in this polygon's frame already: acquire with the same polygon you run. | [`RunAreaOptions`](run-an-analysis.md#runareaoptions).[`buildings`](run-an-analysis.md#runareaoptions-buildings) |
| <a id="runareaandwaitoptions-groundmaterials"></a> `groundMaterials?` | `readonly` | `Readonly`&lt;`Record`&lt;`string`, `unknown`&gt;&gt; \| [`AreaGroundMaterials`](ground-materials.md#areagroundmaterials) | The ground materials: an `AreaGroundMaterials` from `GroundMaterialsService.getArea`, or a bare `{layer: collection}` map. The acquired object carries its read margin, checked as for `vegetation`. | [`RunAreaOptions`](run-an-analysis.md#runareaoptions).[`groundMaterials`](run-an-analysis.md#runareaoptions-groundmaterials) |
| <a id="runareaandwaitoptions-logger"></a> `logger?` | `readonly` | [`Logger`](client.md#logger) | Receives warnings, such as an unrecognised request key. `InfraredClient` passes its own logger. | [`RunAreaOptions`](run-an-analysis.md#runareaoptions).[`logger`](run-an-analysis.md#runareaoptions-logger) |
| <a id="runareaandwaitoptions-maxsensorsperjob"></a> `maxSensorsPerJob?` | `readonly` | `number` | Facade runs only: the most retained sensors one job may carry, a whole number from 1 to 250 000 (the default target). A smaller cap gives more, smaller jobs; each is still an exact, verified count, so a preview with the same cap reports the same jobs and sensors. A retry may omit it or repeat the saved value; a different value is refused. | [`RunAreaOptions`](run-an-analysis.md#runareaoptions).[`maxSensorsPerJob`](run-an-analysis.md#runareaoptions-maxsensorsperjob) |
| <a id="runareaandwaitoptions-maxtilesoverride"></a> `maxTilesOverride?` | `readonly` | `number` | Raises the limit on how many non-empty tiles one run may cover. A run over the limit is refused before anything is submitted, and the message gives the number to pass here. Each tile is a billed job, so size the run with a preview first. | [`RunAreaOptions`](run-an-analysis.md#runareaoptions).[`maxTilesOverride`](run-an-analysis.md#runareaoptions-maxtilesoverride) |
| <a id="runareaandwaitoptions-maxworkers"></a> `maxWorkers?` | `readonly` | `number` | The most requests sent in parallel while submitting jobs. A positive whole number; default 8. Status polling in `runAreaAndWait` has its own default of 5 for the same option. | [`RunAreaOptions`](run-an-analysis.md#runareaoptions).[`maxWorkers`](run-an-analysis.md#runareaoptions-maxworkers) |
| <a id="runareaandwaitoptions-onaccepted"></a> `onAccepted?` | `readonly` | (`jobId`, `tileKey`) => `void` | Called once for each job id the run records, at the moment it records it, with the tile key. A synchronous observer: it only reports, the run does not wait for a returned promise, and an error thrown here is ignored, so the schedule never changes. Use it to store accepted job ids before `runArea` returns (the worker helper sends them to the page this way); a failed store is the caller's to retry. | [`RunAreaOptions`](run-an-analysis.md#runareaoptions).[`onAccepted`](run-an-analysis.md#runareaoptions-onaccepted) |
| <a id="runareaandwaitoptions-onprogress"></a> `onProgress?` | `readonly` | (`state`) => `void` | Called with the run's counts after each submission and status update. | [`RunAreaOptions`](run-an-analysis.md#runareaoptions).[`onProgress`](run-an-analysis.md#runareaoptions-onprogress) |
| <a id="runareaandwaitoptions-retries"></a> `retries?` | `readonly` | `number` | Retry rounds after the run completes, when it left submissions that failed, jobs that failed while computing, or submissions whose outcome is unknown. Default 1; `0` turns retrying off. Each round resubmits only what needs it and waits again; a round that resubmits nothing ends the retrying early. A run is never retried after the API refused it with status 402 (payment required). | - |
| <a id="runareaandwaitoptions-retryfrom"></a> `retryFrom?` | `readonly` | [`AreaSchedule`](run-an-analysis.md#areaschedule) | The schedule of an earlier run of the same area and analysis. The run continues from that saved schedule instead of starting a new one. | [`RunAreaOptions`](run-an-analysis.md#runareaoptions).[`retryFrom`](run-an-analysis.md#runareaoptions-retryfrom) |
| <a id="runareaandwaitoptions-signal"></a> `signal?` | `readonly` | `AbortSignal` | Aborts the run. | [`RunAreaOptions`](run-an-analysis.md#runareaoptions).[`signal`](run-an-analysis.md#runareaoptions-signal) |
| <a id="runareaandwaitoptions-strategy"></a> `strategy?` | `readonly` | `"default"` \| `"directional"` \| `"directional_blend"` | How overlapping tiles are blended. Default `"default"`. `"directional"` and `"directional_blend"` apply to wind-speed analyses only and require `windDirectionDeg`. | [`AreaMergeOptions`](run-an-analysis.md#areamergeoptions).[`strategy`](run-an-analysis.md#areamergeoptions-strategy) |
| <a id="runareaandwaitoptions-terraincontext"></a> `terrainContext?` | `readonly` | [`TerrainContext`](tiling.md#terraincontext) | Not for callers: the SDK builds the terrain context itself. Passing it is refused; use `terrainContextMarginM` instead. | [`RunAreaOptions`](run-an-analysis.md#runareaoptions).[`terrainContext`](run-an-analysis.md#runareaoptions-terraincontext) |
| <a id="runareaandwaitoptions-terraincontextmarginm"></a> `terrainContextMarginM?` | `readonly` | `number` | Metres of terrain read beyond each tile so its edges are seated on real ground. Default 128; the analysis's own minimum wins when it is larger. A retry must repeat the saved value. | [`RunAreaOptions`](run-an-analysis.md#runareaoptions).[`terrainContextMarginM`](run-an-analysis.md#runareaoptions-terraincontextmarginm) |
| <a id="runareaandwaitoptions-transport"></a> `transport?` | `readonly` | `"json"` \| `"binary"` | How the request is sent. Unset: binary, or JSON for an analysis that has no binary route; a retry keeps the transport of the run it continues. Pass `"json"` to force JSON. | [`RunAreaOptions`](run-an-analysis.md#runareaoptions).[`transport`](run-an-analysis.md#runareaoptions-transport) |
| <a id="runareaandwaitoptions-vegetation"></a> `vegetation?` | `readonly` | `Readonly`&lt;`Record`&lt;`string`, `unknown`&gt;&gt; \| [`AreaVegetation`](vegetation.md#areavegetation) | The trees: an `AreaVegetation` from `VegetationService.getArea`, or a bare `{key: feature}` map. The acquired object carries the read margin it was fetched with, and a run whose analysis needs a wider one is refused. | [`RunAreaOptions`](run-an-analysis.md#runareaoptions).[`vegetation`](run-an-analysis.md#runareaoptions-vegetation) |
| <a id="runareaandwaitoptions-webhookevents"></a> `webhookEvents?` | `readonly` | readonly `string`\[\] | The job events that trigger `webhookUrl`. | [`RunAreaOptions`](run-an-analysis.md#runareaoptions).[`webhookEvents`](run-an-analysis.md#runareaoptions-webhookevents) |
| <a id="runareaandwaitoptions-webhookurl"></a> `webhookUrl?` | `readonly` | `string` | A URL the API calls when a job reaches one of `webhookEvents`. | [`RunAreaOptions`](run-an-analysis.md#runareaoptions).[`webhookUrl`](run-an-analysis.md#runareaoptions-webhookurl) |
| <a id="runareaandwaitoptions-winddirectiondeg"></a> `windDirectionDeg?` | `readonly` | `number` | Wind direction in degrees. Required for the directional strategies. | [`AreaMergeOptions`](run-an-analysis.md#areamergeoptions).[`windDirectionDeg`](run-an-analysis.md#areamergeoptions-winddirectiondeg) |

***

<a id="runareainput"></a>

## RunAreaInput

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

> **RunAreaInput** = `Readonly`&lt;`Record`&lt;`string`, `unknown`&gt;&gt; & \{ `analysis-type?`: `never`; `analysisType`: `string`; \} \| \{ `analysis-type`: `string`; `analysisType?`: `never`; \}

The analysis request `runArea` takes: `analysisType` (or the wire key
`"analysis-type"`) plus the analysis's own parameters.

***

<a id="runareainputlike"></a>

## RunAreaInputLike

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

> **RunAreaInputLike** = `Readonly`&lt;`Record`&lt;`string`, `unknown`&gt;&gt;

The analysis request fields `previewAreaBatches` accepts: an object keyed by request field
name.

***

<a id="runareaoptions"></a>

## RunAreaOptions

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

Options for `runArea`, `runAreaAndWait` and `previewAreaBatches`.

### Extended by

- [`RunAreaAndWaitOptions`](run-an-analysis.md#runareaandwaitoptions)

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="runareaoptions-areatimeout"></a> `areaTimeout?` | `readonly` | `number` | `runAreaAndWait` only: seconds to wait for the whole run before it throws `AreaTimeoutError`. A positive number; default 3600. |
| <a id="runareaoptions-buildings"></a> `buildings?` | `readonly` | [`AreaBuildings`](buildings.md#areabuildings) \| `Readonly`&lt;`Record`&lt;`string`, `unknown`&gt;&gt; | The target buildings: an `AreaBuildings` from `BuildingsService.getBuildingsInArea`, or a bare `{buildingId: mesh}` map. An `AreaBuildings` carries `origin` — the frame its bodies are in — and the payload path re-anchors from that origin into this run's site frame, so buildings acquired once for a large area can be run as several sub-areas. A bare map carries no frame and is assumed to be in this polygon's frame already: acquire with the same polygon you run. |
| <a id="runareaoptions-groundmaterials"></a> `groundMaterials?` | `readonly` | `Readonly`&lt;`Record`&lt;`string`, `unknown`&gt;&gt; \| [`AreaGroundMaterials`](ground-materials.md#areagroundmaterials) | The ground materials: an `AreaGroundMaterials` from `GroundMaterialsService.getArea`, or a bare `{layer: collection}` map. The acquired object carries its read margin, checked as for `vegetation`. |
| <a id="runareaoptions-logger"></a> `logger?` | `readonly` | [`Logger`](client.md#logger) | Receives warnings, such as an unrecognised request key. `InfraredClient` passes its own logger. |
| <a id="runareaoptions-maxsensorsperjob"></a> `maxSensorsPerJob?` | `readonly` | `number` | Facade runs only: the most retained sensors one job may carry, a whole number from 1 to 250 000 (the default target). A smaller cap gives more, smaller jobs; each is still an exact, verified count, so a preview with the same cap reports the same jobs and sensors. A retry may omit it or repeat the saved value; a different value is refused. |
| <a id="runareaoptions-maxtilesoverride"></a> `maxTilesOverride?` | `readonly` | `number` | Raises the limit on how many non-empty tiles one run may cover. A run over the limit is refused before anything is submitted, and the message gives the number to pass here. Each tile is a billed job, so size the run with a preview first. |
| <a id="runareaoptions-maxworkers"></a> `maxWorkers?` | `readonly` | `number` | The most requests sent in parallel while submitting jobs. A positive whole number; default 8. Status polling in `runAreaAndWait` has its own default of 5 for the same option. |
| <a id="runareaoptions-onaccepted"></a> `onAccepted?` | `readonly` | (`jobId`, `tileKey`) => `void` | Called once for each job id the run records, at the moment it records it, with the tile key. A synchronous observer: it only reports, the run does not wait for a returned promise, and an error thrown here is ignored, so the schedule never changes. Use it to store accepted job ids before `runArea` returns (the worker helper sends them to the page this way); a failed store is the caller's to retry. |
| <a id="runareaoptions-onprogress"></a> `onProgress?` | `readonly` | (`state`) => `void` | Called with the run's counts after each submission and status update. |
| <a id="runareaoptions-retryfrom"></a> `retryFrom?` | `readonly` | [`AreaSchedule`](run-an-analysis.md#areaschedule) | The schedule of an earlier run of the same area and analysis. The run continues from that saved schedule instead of starting a new one. |
| <a id="runareaoptions-signal"></a> `signal?` | `readonly` | `AbortSignal` | Aborts the run. |
| <a id="runareaoptions-terraincontext"></a> `terrainContext?` | `readonly` | [`TerrainContext`](tiling.md#terraincontext) | Not for callers: the SDK builds the terrain context itself. Passing it is refused; use `terrainContextMarginM` instead. |
| <a id="runareaoptions-terraincontextmarginm"></a> `terrainContextMarginM?` | `readonly` | `number` | Metres of terrain read beyond each tile so its edges are seated on real ground. Default 128; the analysis's own minimum wins when it is larger. A retry must repeat the saved value. |
| <a id="runareaoptions-transport"></a> `transport?` | `readonly` | `"json"` \| `"binary"` | How the request is sent. Unset: binary, or JSON for an analysis that has no binary route; a retry keeps the transport of the run it continues. Pass `"json"` to force JSON. |
| <a id="runareaoptions-vegetation"></a> `vegetation?` | `readonly` | `Readonly`&lt;`Record`&lt;`string`, `unknown`&gt;&gt; \| [`AreaVegetation`](vegetation.md#areavegetation) | The trees: an `AreaVegetation` from `VegetationService.getArea`, or a bare `{key: feature}` map. The acquired object carries the read margin it was fetched with, and a run whose analysis needs a wider one is refused. |
| <a id="runareaoptions-webhookevents"></a> `webhookEvents?` | `readonly` | readonly `string`\[\] | The job events that trigger `webhookUrl`. |
| <a id="runareaoptions-webhookurl"></a> `webhookUrl?` | `readonly` | `string` | A URL the API calls when a job reaches one of `webhookEvents`. |

***

<a id="schedule_contract_version"></a>

## SCHEDULE_CONTRACT_VERSION

Import from `@infrared-city/infrared-sdk-ts`.

> `const` **SCHEDULE\_CONTRACT\_VERSION**: `11` = `11`

The version of the schedule record format this SDK writes into new schedules
(`AreaSchedule.scheduleContractVersion`).

It is raised whenever a field a retry guard depends on is added or changes meaning. A retry
of a schedule written under an older version may be refused by name, with guidance to start
a fresh run.

***

<a id="statussweep"></a>

## StatusSweep

Import from `@infrared-city/infrared-sdk-ts`.

The answer to one batched status request for many jobs.

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="statussweep-batched"></a> `batched` | `readonly` | `boolean` | Whether the service answered in the batched form. |
| <a id="statussweep-failedids"></a> `failedIds?` | `readonly` | readonly `string`\[\] | Ids deferred to the next sweep because the service answered 429 or a 5xx. |
| <a id="statussweep-lacking"></a> `lacking` | `readonly` | `boolean` | Whether the service showed that it does not offer batched status. |
| <a id="statussweep-retryafters"></a> `retryAfterS?` | `readonly` | `number` | The longest `Retry-After` those failures carried, in seconds. |
| <a id="statussweep-statuses"></a> `statuses` | `readonly` | `Map`&lt;`string`, [`Job`](run-an-analysis.md#job)&gt; | The status of each answered job, keyed by job id. |
| <a id="statussweep-unanswered"></a> `unanswered` | `readonly` | `string`\[\] | Ids this request did not settle; read each of these with a single-job status call. |

***

<a id="submitareaplan"></a>

## submitAreaPlan

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

> **submitAreaPlan**(`service`, `plan`, `options?`): `Promise`&lt;[`AreaSchedule`](run-an-analysis.md#areaschedule)&gt;

Submits an already validated plan, one job per entry, and returns the schedule of the run.

A request whose outcome is unknown is not retried; it is recorded in the schedule as uncertain
so you can decide. Failed submissions are recorded too. Pass `options.retryFrom` to continue a
saved schedule.

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `service` | [`AreaJobsService`](run-an-analysis.md#areajobsservice) | The jobs service that sends the jobs, for example `client.jobs`. |
| `plan` | [`AreaSubmissionPlan`](run-an-analysis.md#areasubmissionplan) | The submission plan from `planAreaSubmission`. |
| `options` | [`RunAreaOptions`](run-an-analysis.md#runareaoptions) | The run options: `maxWorkers`, `signal`, `onAccepted`, `onProgress`, `retryFrom`. |

### Returns

`Promise`&lt;[`AreaSchedule`](run-an-analysis.md#areaschedule)&gt;

The frozen schedule of the run.

### Throws

when the API accepted a job with an invalid geometry
  reference, or `retryFrom` records one.

### Throws

when `retryFrom` is a legacy schedule with an uncertain
  capability probe.

***

<a id="tilejobstatus"></a>

## TileJobStatus

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

> **TileJobStatus** = `"pending"` \| `"running"` \| `"completed"` \| `"failed"` \| `"skipped"`

The state of one tile's job: `"pending"`, `"running"`, `"completed"`, `"failed"`, or
`"skipped"` (not run, or no longer polled).

***

<a id="tileposition"></a>

## TilePosition

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

Where one tile sits in the tile grid.

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="tileposition-col"></a> `col` | `readonly` | `number` | Column of the tile in the tile grid. |
| <a id="tileposition-row"></a> `row` | `readonly` | `number` | Row of the tile in the tile grid. |
| <a id="tileposition-tileid"></a> `tileId` | `readonly` | `string` | Identifier of the tile. |

***

<a id="tileprogress"></a>

## TileProgress

Import from `@infrared-city/infrared-sdk-ts`, `@infrared-city/infrared-sdk-ts/tiling`.

A progress report for one tile, passed to a progress callback as a run proceeds.

### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="tileprogress-col"></a> `col` | `readonly` | `number` | Column of the tile in the tile grid. |
| <a id="tileprogress-completedcount"></a> `completedCount` | `readonly` | `number` | Number of tiles completed so far. |
| <a id="tileprogress-elapsedtime"></a> `elapsedTime` | `readonly` | `number` | Time since the run started, in seconds. |
| <a id="tileprogress-finishedcount"></a> `finishedCount` | `readonly` | `number` | Number of tiles that have finished so far. |
| <a id="tileprogress-row"></a> `row` | `readonly` | `number` | Row of the tile in the tile grid. |
| <a id="tileprogress-status"></a> `status` | `readonly` | `"running"` \| `"failed"` \| `"skipped"` \| `"completed"` | State of the tile when reported. |
| <a id="tileprogress-tileid"></a> `tileId` | `readonly` | `string` | Identifier of the tile. |
| <a id="tileprogress-totalcount"></a> `totalCount` | `readonly` | `number` | Total number of tiles in the run. |

***