# Model Inferences

All model inference requests are asynchronous, meaning you must make the request and then poll for the status.

## Request Inference

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

Creates an model inference job to be run on one or more source files

#### Headers

| Name                                            | Type   | Description                                                                                                                                                                                        |
| ----------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | <p>Where you put your api key. Requesting inferences requires a "Model Run" permission on the project where sources exist<br><code>{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}</code></p> |

#### Request Body

| Name                                                    | Type            | Description                                                                                            |
| ------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------ |
| projectIdentifier<mark style="color:red;">\*</mark>     | string          | Identifier of the project that contains the source files. Either id or the unique name of the project. |
| modelIdentifier<mark style="color:red;">\*</mark>       | string          | Identifier of the model that will be run. Either id or the unique name of the model.                   |
| sourceIds<mark style="color:red;">\*</mark>             | array           | array of source ids pointing to where models will be run                                               |
| outputLayerIdentifier<mark style="color:red;">\*</mark> | string\|integer | layer in which predictions will be generated                                                           |
| groupName<mark style="color:red;">\*</mark>             | String          | name of the group user belongs to                                                                      |

{% tabs %}
{% tab title="201 The inference job was created and is in queue" %}

```json
{
    "inferenceJobId": 12,
    "status": "Queued",
    "projectName": "Sample Project",
    "projectId": 1,
    "outputLayerName": "Gold Set",
    "outputLayerId": 12,
    "sourceIds": [3240, 4414],
}
```

{% endtab %}

{% tab title="400 The inference could not be started" %}

```
{
    "message": "explanation for why directory could not be created"
}
```

{% endtab %}
{% endtabs %}

## Request Inference Status

<mark style="color:blue;">`GET`</mark> `https://api.annolab.ai/v1/infer/batch/{job_id}`

Returns the status of the inference job

#### Path Parameters

| Name                                    | Type    | Description                                             |
| --------------------------------------- | ------- | ------------------------------------------------------- |
| jobId<mark style="color:red;">\*</mark> | Integer | Integer representing the inference job that was spawned |

#### Headers

| Name                                            | Type   | Description                                                                                                                                                                                        |
| ----------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | <p>Where you put your api key. Requesting inferences requires a "Model Run" permission on the project where sources exist<br><code>{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}</code></p> |

{% tabs %}
{% tab title="201 The inference job was created and is in queue" %}

```
{
    "inferenceJobId": 12,
    "status": "Queued",
    "projectId": 1,
    "sourceIds": [3240, 4414]
}
```

{% endtab %}

{% tab title="400 The inference could not be started" %}

```
{
    "message": "explanation for why directory could not be created"
}
```

{% endtab %}

{% tab title="404: Not Found Permissions problem or job doesn't exist" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

This code shows how to call a specific model on 2 sources, poll status until the model inference is complete, then retrieve the results.

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

```python
import requests
import time

ANNO_LAB_API_KEY = 'XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX'

inferenceBody = {
  'groupName': 'Company Name',
  'projectIdentifier': 'My Project',
  'sourceIds': [4024, 5853],
  'modelIdentifier': 'Staple + Classify Documents',
  'outputLayerIdentifier': 'Gold Set'
}

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

url = 'https://api.annolab.ai/v1/infer/batch'

response = requests.post(url, headers=headers, json=inferenceBody)

print(response.json())

get_url = 'https://api.annolab.ai/v1/infer/batch/'+response.json()['inferenceJobId']
maximum_timeout_seconds = 1800
time_taken = 0 
inference_is_finished = False

start_time = time.time()
while not inference_is_finished and time_taken < maximum_timeout_seconds:
  status_response = requests.get(get_url, headers=headers, json=inferenceBody).json()
  if status_response['status'] in ['Finished', 'Errored']:
    print("Inference Finished")
    print(status_response)
    inference_is_finished = True
  time_taken = time.time() - start_time
```

{% 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/schemas-ontologies/model-inferences.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.