# Search Instruments

## Search instruments and their data

<mark style="color:blue;">`GET`</mark> `https://api.annolab.ai/v1/instrument/search`

Search a project for information related to instruments that meet search filter criteria. Returns a maximum of 100 instruments and their annotations per page. \
\
If you need individual pdf files exported for each instrument, try using the [Export Instruments api](/exports/export-instruments.md)

#### 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 where you want to search                                                                                                                                                                                                                                                                                                                       |
| tagFilter                                      | Object  | <p>Filter search to include/exclude instruments with tags of these types attached. Applies to instrument's source file tags as well.<br><br>These filters act as an "OR" condition, so specifying two tags means any instrument with either will be returned.<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                                                                                                                                                                                                                                                                        |
| page                                           | Integer | Search result pagination number                                                                                                                                                                                                                                                                                                                                    |

{% tabs %}
{% tab title="201: Created Your search result (100 instruments at a time)" %}

```javascript
{
    'page': 1,
    'hasMorePages': false,
    'results': []
}
```

{% endtab %}
{% endtabs %}

## Search Result Object

| Attribute Name | Type                                                                         | Description                                                          |
| -------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| page           | Integer                                                                      | The page of the search result                                        |
| hasMorePages   | Boolean                                                                      | Whether the search result has additional pages that can be requested |
| results        | [Instrument](/annotations-and-relations/instruments.md#instrument-object)\[] | Array of Instrument objects that comprise the search result          |

```json
{ 
    'page': 1, 
    'hasMorePages': false, 
    'results': []
}
```

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

```python
import requests
import time

ANNO_LAB_API_KEY = 'XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX'

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

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

url = 'https://api.annolab.ai/v1/instrument/search'

response = requests.post(url, headers=headers, json=searchBody, stream=True).json()

search_result = response['results']
#Do something with search result here

#Continue paging your search until there are no more pages 
#(only 100 instruments returned per page)
while response['hasMorePages']:
  searchBody['page'] = response['page'] + 1
  response = requests.get(url, headers=headers, json=searchBody, stream=True).json()
  search_result = response['results']
  #Do something with search result here
  

```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.annolab.ai/search/search-instruments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.