> For the complete documentation index, see [llms.txt](https://help.bioinsight.illumina.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.bioinsight.illumina.com/connected-analytics/api-access/getting-started/api-introduction/run-a-pipeline.md).

# Run a Pipeline

## Combined API Example - Running a Pipeline

Now that we have done individual API requests, we can combine them and use the output of one request as input for the next request. When you want to run a pipeline, you need a number of input parameters. In order to obtain these parameters, you need to make a number of API calls first and use the returned results as part of your request to run the pipeline. In the examples below, we will build up the requests one by one so you can run them individually first to see how they work. These examples only follow the happy path to keep them as simple as possible. If you program them for a full project, remember to add error handling. You can also use the GUI to get all the parameters or write them down after performing the individual API calls in this section. Then, you can build your final API call with those values fixed.

### Initialization

This block must be added at the beginning of your code

```python
# The requests library will allow you to make HTTP requests.
import requests

# JSON will allow us to format and interpret the output.
import json

# Replace <your_generated_API_key> with your actual generated API key here.
headers = {
    'X-API-Key': '<your_generated_API_key>',
}
```

### Look for a project in the list of Projects

Previously, we already requested a list of all projects, now we add a search parameter to look for a project called **MyProject**. (Replace MyProject with the name of the project you want to look for).

{% code overflow="wrap" %}

```python
# Store the API request in response. Here we look for a project called "MyProject".
response = requests.get('https://ica.illumina.com/ica/rest/api/projects?search=MyProject', headers=headers)

# Display the response status code. Code 200 means the request succeeded.
print("Response status code: ", response.status_code)

# Put the JSON data from the response in My_API_Data.
My_API_Data = response.json()

# Print JSON data in readable format with indentation and sorting.
print(json.dumps(My_API_Data, indent=3, sort_keys=True))
```

{% endcode %}

Now that we have found our project by name, we need to get the unique project id, which we will use in the combined requests. To get the id, we add the following line to the end of the code above.

```python
print(My_API_Data['items'][0]['id'])
```

Syntax \['items']\[0]\['id'] means we look for the items list, 0 means we take the first entry (as we presume our filter was accurate enough to only return the correct result and we don't have duplicate project names) and id means we take the data from the id field. Similarly, you can build other expressions to give you the data you want to see, such as \['items']\[0]\['urn'] to get the urn or \['items']\[0]\['tags']\['userTags'] to get the list of user tags.

Once we have the identifier we need, we add it to a variable which we will call Project\_Identifier in our examples.

```python
# Get the project identifier.
Project_Identifier = My_API_Data['items'][0]['id']
```

#### Last usage

You can request the last usage of a pipeline by setting `includePipelineUsage` to true. In this example, we look for the *basic\_pipeline* in the *Getting Started* project.

{% code overflow="wrap" expandable="true" %}

```python
# the requests library will allow you to make HTTP requests
import requests
# json will allow us to format and interpret the output
import json

# Replace <your_generated_API_key> with your actual generated API key here.
headers = {
    'X-API-Key': '<your_generated_API_key>',
}

payload = {
    "name": {
        "equals": "basic_pipeline"
    }
}

# store the api request in response
response = requests.get('https://ica.illumina.com/ica/rest/api/projects?search=Getting Started', headers=headers)

#display the response status code. Code 200 means the request succeeded.
print("Response status code for Project: ", response.status_code)

# put the json data from the response in My_API_Data
My_API_Data = response.json()

# get the project identifier
Project_Identifier = My_API_Data['items'][0]['id']

# store the api request in response. The includePipelineUsage=true paramter will show when and in which analysis the pipeline was last used.
response = requests.post('https://stage.v2.stratus.illumina.com/ica/rest/api/projects/'+(Project_Identifier)+'/pipelines:search?includePipelineUsage=true', headers=headers, json=payload)

#display the response status code. Code 200 means the request succeeded.
print("Response status code for Pipeline: ", response.status_code)

# put the json data from the response in My_API_Data
My_API_Data = response.json()

#Print json data in readable format with indentation and sorting.
print(json.dumps(My_API_Data, indent=3, sort_keys=True))
```

{% endcode %}

### Retrieve the Pipelines of your Project

Once we have the identifier of our project, we can fill it out in the request to list the pipelines which are part of our project.

```python
response = requests.get('https://ica.illumina.com/ica/rest/api/projects/'+(Project_Identifier)+'/pipelines?', headers=headers)
```

This will give us all the available pipelines for that project. As we will only want to run a single pipeline, we can search for our pipeline, which in this example will be the basic\_pipeline. Unfortunately, this API call has no direct search parameter, so when we get the list of pipelines, we will look for the id and store that in a variable which we will call Pipeline\_Identifier in our examples as follows:

{% code overflow="wrap" %}

```python
# Find Pipeline
# Store the API request in response. Here we look for the list of pipelines in MyProject.
response = requests.get('https://ica.illumina.com/ica/rest/api/projects/'+(Project_Identifier)+'/pipelines', headers=headers)

# Display the response status code. Code 200 means the request succeeded.
print("Find Pipeline Response status code: ", response.status_code)

# Put the JSON data from the response in My_API_Data.
My_API_Data = response.json()

# Store the list of pipelines for further processing.
pipelineslist = json.dumps(My_API_Data)

# Set "basic_pipeline" as the pipeline to search for. Replace this with your target pipeline.
target_pipeline = "basic_pipeline"
found_pipeline = None

# Look for the code to match basic_pipeline and store the ID.
for item in My_API_Data['items']:
    if 'pipeline' in item and item['pipeline'].get('code') == target_pipeline:
        found_pipeline = item['pipeline']
        Pipeline_Identifier = found_pipeline['id']
        break
print("Pipeline Identifier: " + Pipeline_Identifier)
```

{% endcode %}

### Find which parameters the Pipeline needs.

Once we know the project identifier and the pipeline identifier, we can create an API request to retrieve the list of input parameters which are needed for the pipeline. We will consider a simple pipeline which only needs a file as input. If your pipeline has more input parameters, you will need to set those as well.

{% code overflow="wrap" %}

```python
# Find Parameters
# Store the API request in response. Here we look for the Parameters in basic_pipeline
response = requests.get('https://ica.illumina.com/ica/rest/api/pipelines/'+(Pipeline_Identifier)+'/inputParameters', headers=headers)

# Display the response status code. Code 200 means the request succeeded.
print("Find Parameters Response status code: ", response.status_code)

# Put the JSON data from the response in My_API_Data.
My_API_Data = response.json()

# Get the parameters and store in the Parameters variable.
Parameters = My_API_Data['items'][0]['code']
print("Parameters: ",Parameters)
```

{% endcode %}

### Find the Storage Size to use for the analysis.

Here we will look for the id of the extra small storage size. This is done with the 0 in the My\_API\_Data\['items']\[0]\['id']

{% code overflow="wrap" %}

```python
# Store the API request in response. Here we look for the analysis storage size.
response = requests.get('https://ica.illumina.com/ica/rest/api/projects/'+(Project_Identifier)+'/analysisStorages', headers=headers)

# Display the response status code. Code 200 means the request succeeded.
print("Find analysisStorages Response status code: ", response.status_code)

# Put the JSON data from the response in My_API_Data.
My_API_Data = response.json()

# Get the storage size. We will select the smallest size.
Storage_Size = My_API_Data['items'][0]['id']
print("Storage_Size: ",Storage_Size)
```

{% endcode %}

### Find the files to use as input for your pipeline.

Now we will look for a file "testExample" which we want to use as input and store the file id.

{% code overflow="wrap" %}

```python
# Get Input File
# Store the API request in response. Here we look for the Files testExample.
response = requests.get('https://ica.illumina.com/ica/rest/api/projects/'+(Project_Identifier)+'/data?fullText=testExample', headers=headers)

# Display the response status code. Code 200 means the request succeeded.
print("Find input file Response status code: ", response.status_code)

# Put the JSON data from the response in My_API_Data
My_API_Data = response.json()

# Get the first file ID.
InputFile = My_API_Data['items'][0]['data']['id']
print("InputFile id: ",InputFile)
```

{% endcode %}

### Start the Pipeline.

Finally, we can run the analysis with parameters filled out.

{% code overflow="wrap" %}

```python
Postheaders = {
    'accept': 'application/vnd.illumina.v4+json',
    'X-API-Key': '<your_generated_API_key>',
    'Content-Type': 'application/vnd.illumina.v4+json',
}

data = '{"userReference":"api_example","pipelineId":"'+(Pipeline_Identifier)+'","analysisStorageId":"'+(Storage_Size)+'","analysisInput":{"inputs":[{"parameterCode":"'+(Parameters)+'","dataIds":["'+(InputFile)+'"]}]}}'

response = requests.post(
    'https://ica.illumina.com/ica/rest/api/projects/'+(Project_Identifier)+'/analysis:nextflow',headers=Postheaders,data=data,
)
```

{% endcode %}

### Complete code example

{% code expandable="true" %}

```python
# The requests library will allow you to make HTTP requests.
import requests

# JSON will allow us to format and interpret the output.
import json

# Replace <your_generated_API_key> with your actual generated API key here.
headers = {
    'X-API-Key': '<your_generated_API_key>',
}

# Replace <your_generated_API_key> with your actual generated API key here.
Postheaders = {
    'accept': 'application/vnd.illumina.v4+json',
    'X-API-Key': '<your_generated_API_key>',
    'Content-Type': 'application/vnd.illumina.v4+json',
}

# Find project
# Store the API request in response. Here we look for a project called "MyProject".
response = requests.get('https://ica.illumina.com/ica/rest/api/projects?search=MyProject', headers=headers)

# Display the response status code. Code 200 means the request succeeded.
print("Find Project response status code: ", response.status_code)

# Put the JSON data from the response in My_API_Data.
My_API_Data = response.json()

# Get the project identifier.
Project_Identifier = My_API_Data['items'][0]['id']
print("Project_Identifier: ",Project_Identifier)

# Find Pipeline
# Store the API request in response. Here we look for the list of pipelines in MyProject.
response = requests.get('https://ica.illumina.com/ica/rest/api/projects/'+(Project_Identifier)+'/pipelines', headers=headers)

# Display the response status code. Code 200 means the request succeeded.
print("Find Pipeline Response status code: ", response.status_code)

# Put the JSON data from the response in My_API_Data.
My_API_Data = response.json()

# Store the list of pipelines for further processing.
pipelineslist = json.dumps(My_API_Data)

# Set "basic_pipeline" as the pipeline to search for. Replace this with your target pipeline.
target_pipeline = "basic_pipeline"
found_pipeline = None

# Look for the code to match basic_pipeline and store the ID.
for item in My_API_Data['items']:
    if 'pipeline' in item and item['pipeline'].get('code') == target_pipeline:
        found_pipeline = item['pipeline']
        Pipeline_Identifier = found_pipeline['id']
        break
print("Pipeline Identifier: " + Pipeline_Identifier)

# Find Parameters
# Store the API request in response. Here we look for the Parameters in basic_pipeline.
response = requests.get('https://ica.illumina.com/ica/rest/api/pipelines/'+(Pipeline_Identifier)+'/inputParameters', headers=headers)

# Display the response status code. Code 200 means the request succeeded.
print("Find Parameters Response status code: ", response.status_code)

# Put the JSON data from the response in My_API_Data.
My_API_Data = response.json()

# Get the parameters and store in the Parameters variable.
Parameters = My_API_Data['items'][0]['code']
print("Parameters: ",Parameters)

# Get Storage Size
# Store the API request in response. Here we look for the analysis storage size.
response = requests.get('https://ica.illumina.com/ica/rest/api/projects/'+(Project_Identifier)+'/analysisStorages', headers=headers)

# Display the response status code. Code 200 means the request succeeded.
print("Find analysisStorages Response status code: ", response.status_code)

# Put the JSON data from the response in My_API_Data.
My_API_Data = response.json()

# Get the storage size. We will select the smallest size.
Storage_Size = My_API_Data['items'][0]['id']
print("Storage_Size: ",Storage_Size)

# Get Input File
# Store the API request in response. Here we look for the Files testExample.
response = requests.get('https://ica.illumina.com/ica/rest/api/projects/'+(Project_Identifier)+'/data?fullText=testExample', headers=headers)

# Display the response status code. Code 200 means the request succeeded.
print("Find input file Response status code: ", response.status_code)

# Put the JSON data from the response in My_API_Data.
My_API_Data = response.json()

# Get the first file ID.
InputFile = My_API_Data['items'][0]['data']['id']
print("InputFile id: ",InputFile)

# Finally, we can run the analysis with parameters filled out.
data = '{"userReference":"api_example","pipelineId":"'+(Pipeline_Identifier)+'","tags":{"technicalTags":[],"userTags":[],"referenceTags":[]},"analysisStorageId":"'+(Storage_Size)+'","analysisInput":{"inputs":[{"parameterCode":"'+(Parameters)+'","dataIds":["'+(InputFile)+'"]}]}}'
print (data)
response = requests.post('https://ica.illumina.com/ica/rest/api/projects/'+(Project_Identifier)+'/analysis:nextflow',headers=Postheaders,data=data,)
print("Post Response status code: ", response.status_code)
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.bioinsight.illumina.com/connected-analytics/api-access/getting-started/api-introduction/run-a-pipeline.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.