---
title: "Download one member of a finished 3D extract"
description: "Streams a single output file of the job by its exact name as listed in the status `files` array. Only allowlisted members are served - matched by extension (`.obj`, `.mtl`, `.dxf`, `.dwg`, `.gpkg`, `.zip`) or basename (`buildings.json`, `preview.png`, `README.txt`); anything else in the job directory (state.json, result.json, temp files) answers 404. Names containing path separators or `..` answer 400. Sent with `Content-Disposition: attachment` and `Accept-Ranges: bytes`. 409 while queued/running, 410 when the job failed.\n\nAccepts the token in the `token` header or as `?token=` so the URL works from `<a href>` and from a Grasshopper HTTP fetch."
---

> 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/download/{jobId}/{file}`

Streams a single output file of the job by its exact name as listed in the status `files` array. Only allowlisted members are served - matched by extension (`.obj`, `.mtl`, `.dxf`, `.dwg`, `.gpkg`, `.zip`) or basename (`buildings.json`, `preview.png`, `README.txt`); anything else in the job directory (state.json, result.json, temp files) answers 404. Names containing path separators or `..` answer 400. Sent with `Content-Disposition: attachment` and `Accept-Ranges: bytes`. 409 while queued/running, 410 when the job failed.

Accepts the token in the `token` header or as `?token=` so the URL works from `<a href>` and from a Grasshopper HTTP fetch.

## Authentication

Requires one of the following:

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

## Path parameters

- `jobId` (`downloadBuilding3dExtractFile.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}$`
- `file` (`downloadBuilding3dExtractFile.path.file`; string, required): Exact member name from the status `files` list (e.g. `rainweg_1_4710_balsthal.obj`, `model.mtl`, `buildings.json`, `preview.png`, `README.txt`, the `_clip.gpkg` or the zip), OR a bare extension alias - `obj`, `mtl`, `dxf`, `dwg`, `gpkg`, `zip` - which resolves to the job's first member with that extension so a client can build the URL without reading the status first.
  - maxLength 120; pattern `^[A-Za-z0-9][A-Za-z0-9._-]{0,119}$`

## Query parameters

- `token` (`downloadBuilding3dExtractFile.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/download/<jobId>/rainweg_1_4710_balsthal.obj' \
  --header 'token: <token>'
```

### TypeScript

```typescript
const url = 'https://res.aireon.ch/res_api/building3d-extract/download/<jobId>/rainweg_1_4710_balsthal.obj';
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/download/<jobId>/rainweg_1_4710_balsthal.obj"

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

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

print(response.text)
```

## Responses

### 200

The file bytes. Content-Type follows the extension (text/plain for OBJ/MTL/README, image/png, application/json, application/geopackage+sqlite3, image/vnd.dxf, image/vnd.dwg, application/zip); clients that do not care can read it as octets.

#### Example

```text
string
```

### 400

`jobId` is not a UUID v4, or `file` contains a path separator / `..`.

#### Example

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

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

### 401

Authentication missing or invalid.

#### Example

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

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

### 403

Authenticated but not permitted.

#### Example

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

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

### 404

Unknown job, or `file` is not an allowlisted member of this job.

#### Example

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

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

### 409

The job is still queued or running - poll `statusUrl` and retry once `status` is `ready`.

#### Example

```json
{
  "error": "string",
  "status": "queued",
  "phase": "string",
  "statusUrl": "string"
}
```

- `error` (`downloadBuilding3dExtractFile.response.409.error`; string, required)
- `status` (`downloadBuilding3dExtractFile.response.409.status`; string, required)
  - one of `"queued"`, `"running"`
- `phase` (`downloadBuilding3dExtractFile.response.409.phase`; string | null, optional)
- `statusUrl` (`downloadBuilding3dExtractFile.response.409.statusUrl`; string, optional)

### 410

The job failed (unknown address, no swissBUILDINGS3D 3.0 tile covering the point, empty box, worker crash) or its output has been evicted; `error` says why. Nothing will ever be downloadable for this jobId - start a new job.

#### Example

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

- `error` (`downloadBuilding3dExtractFile.response.410.error`; string, required)
- `status` (`downloadBuilding3dExtractFile.response.410.status`; string, required)
  - one of `"error"`


Source: https://docs.aireon.ch/res/download-building3d-extract-file/index.md