# Export Instruments

## Export instruments and their data

<mark style="color:green;">`POST`</mark> `https://api.annolab.ai/v1/export/instruments`

Export all information related to instruments that meet filter criteria. Can include annotation data, source files, and tags.

#### Headers

| Name                                            | Type   | Description                                                                                                                                                         |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | <p>Where you put your api key. Exporting a project requires a key with "Read" permissions.<br><code>{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}</code></p> |

#### Request Body

| Name                                           | Type    | Description                                                                                                                                                                                                                                                                                                                                                              |
| ---------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| projectOwner<mark style="color:red;">\*</mark> | String  | Group Name that owns the project (viewable in "All Projects" page)                                                                                                                                                                                                                                                                                                       |
| projectName<mark style="color:red;">\*</mark>  | String  | Name of the project you wish to export from                                                                                                                                                                                                                                                                                                                              |
| tagFilter                                      | Object  | <p>Filter export to include/exclude instruments with tags of these types attached. Applies to instrument's source file tags as well.</p><p></p><p>These filters act as an "OR" condition, so specifying two tags means any instrument with either will be exported.<br><code>{"includeTypes": \["Airframe Inventory"], "excludeTypes": \["Engine Inventory"]}</code></p> |
| sourceFilter                                   | String  | Filters export to only those instruments that have a source file name equal to sourceFilter                                                                                                                                                                                                                                                                              |
| includeFiles                                   | Boolean | If true, splits each instrument into individual files for export                                                                                                                                                                                                                                                                                                         |

{% tabs %}
{% tab title="201: Created Export Request created. Response contains information on how to check status of export request" %}

```javascript
{
    'message': "Export Request Successful. To check export status make a GET request at exportStatusUrl in response body",
    'exportStatusUrl': "https://api.annolab.ai/v1/export/status/341",
    'exportJob': {'id': 341, 'status': "initialized", 'projectId': 148, 'isInstrumentsExport': true}
}
```

{% endtab %}
{% endtabs %}

This code shows how to request an instrument export, then download the export contents.

{% tabs %}
{% tab title="Python" %}

<pre class="language-python"><code class="lang-python">import requests
import time

ANNO_LAB_API_KEY = 'XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX'

exportRequestBody = {
  'projectOwner': 'Group Name owning project',
  'projectName': 'Example Project Name',
  'tagFilter': {
    'includeTypes': ["Airframe Inventory"],
    'excludeTypes': ["Engine Inventory"],
  },
  'sourceFilter': "Test_PDF.pdf",
  'includeFiles': True
}

headers = {
  'Authorization': 'Api-Key '+ANNO_LAB_API_KEY,
}

url = 'https://api.annolab.ai/v1/export/instruments'

<strong>response = requests.post(url, headers=headers, json=exportRequestBody, stream=True)
</strong>
status_url = response.json()['exportStatusUrl']
export_status = response.json()['exportJob']['status']

if response.status_code == 201:
  while export_status not in ['finished', 'errored']:
    response = requests.get(status_url, headers=headers).json()
    print(response)
    export_status = response['status']
    if export_status not in ['finished', 'errored']:
      time.sleep(15)
  
  if export_status == 'finished':
    signed_url = response['downloadUrl']
    download_response = requests.get(signed_url, stream=True)
    export_file_name = 'example_export.zip'
    if download_response.status_code == 200:
      with open(export_file_name, 'wb') as f:
        for chunk in download_response.iter_content(1024):
          f.write(chunk)
    print("Export download finished see: ", export_file_name)
    
</code></pre>

{% endtab %}
{% endtabs %}

### Example Export Format

Once an export is completed, you will see a zip file on your file system

<figure><img src="https://2539662686-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MR10rNw-iCGaHMIJEII%2Fuploads%2FAa0ymP6cqAzNIfw6XkTV%2FScreen%20Shot%202022-12-18%20at%205.03.49%20PM.png?alt=media&#x26;token=c47602c2-2114-4694-bb49-49b1c17082ed" alt=""><figcaption></figcaption></figure>

Opening the zip file will reveal one .json (jsonlines file) and a folder named pdfs (if you specified `includeFiles: true` in your export request)

<figure><img src="https://2539662686-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MR10rNw-iCGaHMIJEII%2Fuploads%2FVDMPO2SMYKNDmAQT8v5d%2FScreen%20Shot%202022-12-18%20at%205.09.21%20PM.png?alt=media&#x26;token=c01feb75-1047-4225-bcf8-51d864a35dec" alt=""><figcaption><p>example_export.zip extracted</p></figcaption></figure>

Exported instrument pdfs will have a name of the form `<Instrument Type>_<page start>-<page end>_<instrument id>.pdf`

The  `instruments.json` file will contain json lines of [Instrument Objects](https://docs.annolab.ai/annotations-and-relations/instruments#instrument-object)