---
title: "Poll a 3D extract job"
description: "Reads the job directory on disk (cache/building3d/jobs/<jobId>/): `result.json`, written by the worker when it finishes, decides `ready` (ok) or `error` (with the message); until then `state.json` - written by the route at spawn time and updated by the worker with a `phase` (geocoding/locating, tile, clip, build, zip, email) - reports `queued` or `running`. Disk is the truth, so a poll may hit either pm2 cluster worker. A job still `running` with no update for 60 minutes is reported as `error` (stale). When the directory has been evicted, the 24 h Redis mirror is consulted as a fallback and a formerly `ready` job is reported as `error` (nothing left to download); with neither, 404.\n\nAccepts the token in the `token` header or as `?token=` so the URL can be polled from a Grasshopper HTTP component or a browser."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.aireon.ch/llms.txt
> Use this file to discover all available pages before exploring further.

Path: RES API (public) › Building3D

`GET /res_api/building3d-extract/status/{jobId}`

Reads the job directory on disk (cache/building3d/jobs/<jobId>/): `result.json`, written by the worker when it finishes, decides `ready` (ok) or `error` (with the message); until then `state.json` - written by the route at spawn time and updated by the worker with a `phase` (geocoding/locating, tile, clip, build, zip, email) - reports `queued` or `running`. Disk is the truth, so a poll may hit either pm2 cluster worker. A job still `running` with no update for 60 minutes is reported as `error` (stale). When the directory has been evicted, the 24 h Redis mirror is consulted as a fallback and a formerly `ready` job is reported as `error` (nothing left to download); with neither, 404.

Accepts the token in the `token` header or as `?token=` so the URL can be polled from a Grasshopper HTTP component or a browser.

## Authentication

Requires one of the following:

- `ResApiToken`, apiKey, in header, header `token`
- `ResApiTokenQuery`, apiKey, in query

## Path parameters

- `jobId` (`getBuilding3dExtractStatus.path.jobId`; string, required): Job id from the 202 of `POST /res_api/building3d-extract` (UUID v4).
  - format `uuid`; pattern `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$`

## Query parameters

- `token` (`getBuilding3dExtractStatus.query.token`; string, optional): The RES API token as a query parameter - alternative to the `token` header for links and header-less HTTP fetches (Grasshopper). Treat the resulting URL as a credential.

## Code samples

### cURL

```bash
curl --request GET \
  --url 'https://res.aireon.ch/res_api/building3d-extract/status/<jobId>' \
  --header 'token: <token>'
```

### TypeScript

```typescript
const url = 'https://res.aireon.ch/res_api/building3d-extract/status/<jobId>';
const options = {method: 'GET', headers: {token: '<token>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://res.aireon.ch/res_api/building3d-extract/status/<jobId>"

headers = {"token": "<token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

## Responses

### 200

Current job state. `files` is empty until `ready`; `downloadUrl` is set only when `ready`.

#### Example

```json
{
  "jobId": "9d222c6d-893e-4e79-8201-3c9ca16a0f39",
  "status": "queued",
  "phase": "string",
  "files": [
    {
      "name": "string",
      "bytes": 0
    }
  ],
  "error": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "address": "string",
  "radius_m": 0,
  "statusUrl": "string",
  "downloadUrl": "string"
}
```

- `jobId` (`getBuilding3dExtractStatus.response.200.jobId`; string, required)
  - format `uuid`
- `status` (`getBuilding3dExtractStatus.response.200.status`; string, required): `queued`: accepted, worker not started yet; `running`: worker in progress (see `phase`); `ready`: result.json says ok - download now; `error`: failed, stale, or evicted - see `error`.
  - one of `"queued"`, `"running"`, `"ready"`, `"error"`
- `files` (`getBuilding3dExtractStatus.response.200.files`; array<object>, required): Downloadable members (empty until `ready`).
  - `name` (`getBuilding3dExtractStatus.response.200.files.name`; string, required): Member name, usable as `{file}` on the download endpoint.
  - `bytes` (`getBuilding3dExtractStatus.response.200.files.bytes`; integer, required)
    - min 0
- `error` (`getBuilding3dExtractStatus.response.200.error`; string | null, required)
- `createdAt` (`getBuilding3dExtractStatus.response.200.createdAt`; string | null, required)
  - format `date-time`
- `updatedAt` (`getBuilding3dExtractStatus.response.200.updatedAt`; string | null, required): Last state change; the worker's `finishedAt` once a result exists.
  - format `date-time`
- `phase` (`getBuilding3dExtractStatus.response.200.phase`; string | null, optional): Worker progress while running (`starting`, `geocoding` or `locating`, `tile`, `clip`, `build`, `zip`, `email`), `done` when ready, `failed` on error.
- `address` (`getBuilding3dExtractStatus.response.200.address`; string | null, optional): Address (or resolved label) of the request.
- `radius_m` (`getBuilding3dExtractStatus.response.200.radius_m`; number | null, optional)
- `statusUrl` (`getBuilding3dExtractStatus.response.200.statusUrl`; string, optional)
- `downloadUrl` (`getBuilding3dExtractStatus.response.200.downloadUrl`; string | null, optional): Set only when `status` is `ready`.

### 400

`jobId` is not a UUID v4.

#### Example

```json
{
  "error": "string",
  "message": "string"
}
```

- `error` (`getBuilding3dExtractStatus.response.400.error`; string, required): Human-readable error description.
- `message` (`getBuilding3dExtractStatus.response.400.message`; string, optional): Optional underlying error message.

### 401

Authentication missing or invalid.

#### Example

```json
{
  "error": "string",
  "message": "string"
}
```

- `error` (`getBuilding3dExtractStatus.response.401.error`; string, required): Human-readable error description.
- `message` (`getBuilding3dExtractStatus.response.401.message`; string, optional): Optional underlying error message.

### 403

Authenticated but not permitted.

#### Example

```json
{
  "error": "string",
  "message": "string"
}
```

- `error` (`getBuilding3dExtractStatus.response.403.error`; string, required): Human-readable error description.
- `message` (`getBuilding3dExtractStatus.response.403.message`; string, optional): Optional underlying error message.

### 404

Resource not found.

#### Example

```json
{
  "error": "string",
  "message": "string"
}
```

- `error` (`getBuilding3dExtractStatus.response.404.error`; string, required): Human-readable error description.
- `message` (`getBuilding3dExtractStatus.response.404.message`; string, optional): Optional underlying error message.


Source: https://docs.aireon.ch/res/get-building3d-extract-status/index.md