# Analysis Jobs

{% hint style="info" %}
The public API supports submitting analysis jobs. To submit an analysis job, you must have already uploaded the files you wish to analyze to the Biodock filesystem, and you must have a published analysis pipeline. 
{% endhint %}

{% hint style="info" %}
Pipelines can only be created and published through the website, NOT the API.
{% endhint %}

{% hint style="info" %}
Only user-created pipelines are supported through the public API, NOT Biodock pipelines.
{% endhint %}

To submit an analysis job, use the following endpoint:

## Submit analysis job

<mark style="color:green;">`POST`</mark> `https://app.biodock.ai/api/external/analysis-jobs`

#### Headers

| Name                                        | Type   | Description |
| ------------------------------------------- | ------ | ----------- |
| X-API-KEY<mark style="color:red;">\*</mark> | String | API key.    |

#### Request Body

| Name                                            | Type          | Description                   |
| ----------------------------------------------- | ------------- | ----------------------------- |
| pipelineId<mark style="color:red;">\*</mark>    | String        | Pipeline to use for analysis. |
| filesystemIds<mark style="color:red;">\*</mark> | List\[String] | Filesystem items to analyze.  |
| name                                            | String        | Name of the job.              |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    id: "0123456789",
    percentageCompleted: 0,
    status: "PENDING"
}
```

{% endtab %}
{% endtabs %}

You can view progress for your analysis job using the following endpoint:

## Fetch analysis job

<mark style="color:blue;">`GET`</mark> `https://app.biodock.ai/api/external/analysis-jobs/{id}`

#### Path Parameters

| Name                                 | Type   | Description |
| ------------------------------------ | ------ | ----------- |
| id<mark style="color:red;">\*</mark> | String |             |

#### Headers

| Name                                        | Type   | Description |
| ------------------------------------------- | ------ | ----------- |
| X-API-KEY<mark style="color:red;">\*</mark> | String | API key.    |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    id: "0123456789",
    percentageCompleted: 100,
    status: "SUCCEEDED",
    objectsDataCSVUrl: "https://...",
    aggregateDataCSVUrl: "https://..."
}
```

{% endtab %}
{% endtabs %}

You can view progress for all your analysis jobs using the following endpoint:

## List analysis jobs

<mark style="color:blue;">`GET`</mark> `https://app.biodock.ai/api/external/analysis-jobs`

#### Query Parameters

| Name          | Type   | Description                        |
| ------------- | ------ | ---------------------------------- |
| limit         | Number | Maximum number of results to show. |
| startingAfter | String | Pagination cursor id.              |

#### Headers

| Name                                        | Type   | Description |
| ------------------------------------------- | ------ | ----------- |
| X-API-KEY<mark style="color:red;">\*</mark> | String | API key.    |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    results: [{
        id: "0123456789",
        percentageCompleted: 100,
        status: "SUCCEEDED",
        objectsDataCSVUrl: "https://...",
        aggregateDataCSVUrl: "https://..."
    }],
    count: 1
}
```

{% endtab %}
{% endtabs %}

Masks data is not generated by default during an analysis job. If you would like to obtain the masks data for your analysis job, you must first generate the masks data with the following endpoint:

## Submit download masks job

<mark style="color:green;">`POST`</mark> `https://app.biodock.ai/api/external/analysis-jobs/{id}/download-masks`

#### Path Parameters

| Name                                 | Type   | Description |
| ------------------------------------ | ------ | ----------- |
| id<mark style="color:red;">\*</mark> | String |             |

#### Headers

| Name                                        | Type   | Description |
| ------------------------------------------- | ------ | ----------- |
| X-API-KEY<mark style="color:red;">\*</mark> | String | API key.    |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    percentageCompleted: 0,
    status: "SUBMITTED"
}
```

{% endtab %}
{% endtabs %}

Once the masks generation has completed, the download link to the masks will be available. You can view the progress and obtain the download link with the following endpoint:

## Fetch download masks job

<mark style="color:blue;">`GET`</mark> `https://app.biodock.ai/api/external/analysis-jobs/{id}/download-masks`

#### Path Parameters

| Name                                 | Type   | Description |
| ------------------------------------ | ------ | ----------- |
| id<mark style="color:red;">\*</mark> | String |             |

#### Headers

| Name                                        | Type   | Description |
| ------------------------------------------- | ------ | ----------- |
| X-API-KEY<mark style="color:red;">\*</mark> | String | API key.    |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    percentageCompleted: 100,
    status: "SUCCEEDED",
    masksZipUrl: "https://..."
}
```

{% endtab %}
{% endtabs %}

### Sample Usage

Submitting an analysis job

```python
import requests

API_KEY = "" # Replace with your api key
FILESYSTEM_IDS = [""] # Replace with your filesystem ids. Add to the list as neccesary
PIPELINE_ID = "" # Replace with your pipeline id

URL = "https://app.biodock.ai/api/external/analysis-jobs"
headers = {"X-API-KEY": API_KEY, "Content-Type": "application/json"}
data = {"filesystemIds": FILESYSTEM_IDS, "pipelineId": PIPELINE_ID}

response = requests.post(URL, json=data, headers=headers)
print(response.text)

```

View the progress of a specific analysis job

```python
import requests

API_KEY = "" # Replace with your api key
ANALYSIS_JOB_ID = "" # Replace with your analysis job id

URL = f"https://app.biodock.ai/api/external/analysis-jobs/{ANALYSIS_JOB_ID}"
headers = {"X-API-KEY": API_KEY, "Content-Type": "application/json"}

response = requests.get(URL, headers=headers)
print(response.text)
```

View the progress of all your analysis jobs

```python
import requests

API_KEY = "" # Replace with your api key

URL = "https://app.biodock.ai/api/external/analysis-jobs"
headers = {"X-API-KEY": API_KEY, "Content-Type": "application/json"}

response = requests.get(URL, headers=headers)
print(response.text)
```

Generate masks data for an analysis job

```python
import requests

API_KEY = "" # Replace with your api key
ANALYSIS_JOB_ID = "" # Replace with your analysis job id

URL = f"https://app.biodock.ai/api/external/analysis-jobs/{ANALYSIS_JOB_ID}/download-masks"
headers = {"X-API-KEY": API_KEY, "Content-Type": "application/json"}

response = requests.post(URL, headers=headers)
print(response.text)
```

View the progress of masks generation

```python
import requests

API_KEY = "" # Replace with your api key
ANALYSIS_JOB_ID = "" # Replace with your analysis job id

URL = f"https://app.biodock.ai/api/external/analysis-jobs/{ANALYSIS_JOB_ID}/download-masks"
headers = {"X-API-KEY": API_KEY, "Content-Type": "application/json"}

response = requests.get(URL, headers=headers)
print(response.text)
```


---

# 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.biodock.ai/public-api-beta/resources/analysis-jobs.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.