> For the complete documentation index, see [llms.txt](https://knowledge.illumina.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://knowledge.illumina.com/software/general/software-general-reference_material-list/000003682.md).

# How to list BaseSpace entities using BaseSpace Command Line Interface (CLI)

One of the key features of the [BaseSpace CLI](https://developer.basespace.illumina.com/docs/content/documentation/cli/cli-overview) tool is the ability to list the various entities, such as Runs, Projects and Biosamples accessible by the current BaseSpace account. This includes entities that are either owned by or shared with the current user. The list command is a quick way to get IDs and Names of entities, which can then be used as input into downstream BaseSpace CLI commands. In its simplest form the list command is structured as below:

```
bs list <entity>  
```

Available BaseSpace entities: **appresult**, **appsession**, **biosample**, **dataset**, **project**, **run**, **trash**

The example below is a truncated output listing all **Runs** accessible under the current BaseSpace account. The default output is a table format that is easy for humans to read:

```
bs list run  
+------------------------------------------------------------------+-----------+-------------------------------------------------------------------+------------------+  
|                               Name                               |    Id     |                          ExperimentName                           |      Status      |  
+------------------------------------------------------------------+-----------+-------------------------------------------------------------------+------------------+  
| 150109_NS000000_0203_ANextSeq_500_V2_RNA-Seq_(8plex)_-_H3GYJBGXX | 10149162  | NextSeq 500 V2: RNA-Seq (8plex) - H3GYJBGXX                       | Complete         |  
| 150123_P0000_0319_ANextSeq_500_V2_Nano350_(PhiX)_H3GNKBGXX       | 10383420  | NextSeq 500 V2: Nano350 (PhiX)_H3GNKBGXX                          | Complete         |  
| 160907_NB000000_0241_AH2LWNBGXY                                  | 20865846  | TruSight_Tumor_170_Example_Dataset                                | Complete         |  
| 170220_A00000_0014_AHMWVDMCVY                                    | 23564552  | NovaSeq: TruSeq Nano 550 (Replicates of NA12878)                  | Failed           |  
...  
```

**Fields**\
In the table output, above the column titles (headers) are the default "fields" printed with the simple list run command. These fields can be specified using the `-F <field>` flag combination in the command to provide more or less information about each result, and tailor the output.

```
bs list run -F ExperimentName -F Id -F UserOwnedBy.Name  
+-------------------------------------------------------------------+-----------+-----------------------------------+  
|                          ExperimentName                           |    Id     |         UserOwnedBy.Name          |  
+-------------------------------------------------------------------+-----------+-----------------------------------+  
| NextSeq 500 V2: RNA-Seq (8plex) - H3GYJBGXX                       | 10149162  | Illumina Inc                      |  
| NextSeq 500 V2: Nano350 (PhiX)_H3GNKBGXX                          | 10383420  | Illumina Public Data              |  
| TruSight_Tumor_170_Example_Dataset                                | 20865846  | Illumina Public Data              |  
| NovaSeq: TruSeq Nano 550 (Replicates of NA12878)                  | 23564552  | Illumina Public Data              |  
...  
```

The various fields can be used to filter results, avoiding the need to print and search through the entire list of entities. To do so, specify the `--filter-field` flag and the `--filter-term` flag. The CLI will return only results where the field designated with the `--filter-field` flag contains the string designated with the `--filter-term` flag.

```
bs list run --filter-field ExperimentName --filter-term NovaSeq  
+----------------------------------------------------+-----------+----------------------------------------------------+----------+  
|                        Name                        |    Id     |                   ExperimentName                   |  Status  |  
+----------------------------------------------------+-----------+----------------------------------------------------+----------+  
| 170220_A00000_0014_AHMWVDMCVY                      | 23564552  | NovaSeq: TruSeq Nano 550 (Replicates of NA12878)   | Failed   |  
+----------------------------------------------------+-----------+----------------------------------------------------+----------+  
```

**Filtering**\
In the example above, the results are limited to only those runs where the case-sensitive string "NovaSeq" is found in the field **ExperimentName**. The string listed in `--filter-term` can comprise all, or part, of the field listed in `--filter-field`. For example, simply using the string "Seq" will return more matches.

```
bs list run --filter-field ExperimentName --filter-term Seq  
+------------------------------------------------------------------+-----------+----------------------------------------------------+----------+  
|                               Name                               |    Id     |                   ExperimentName                   |  Status  |  
+------------------------------------------------------------------+-----------+----------------------------------------------------+----------+  
| 150109_NS000000_0203_ANextSeq_500_V2_RNA-Seq_(8plex)_-_H3GYJBGXX | 10149162  | NextSeq 500 V2: RNA-Seq (8plex) - H3GYJBGXX        | Complete |  
| 150123_P0000_0319_ANextSeq_500_V2_Nano350_(PhiX)_H3GNKBGXX       | 10383420  | NextSeq 500 V2: Nano350 (PhiX)_H3GNKBGXX           | Complete |  
| 170220_A00000_0014_AHMWVDMCVY                                    | 23564552  | NovaSeq: TruSeq Nano 550 (Replicates of NA12878)   | Failed   |  
| 180117_SN000_0713_ACBTVAANXX                                     | 59519461  | HiSeq 2500: TruSight Oncology UMI Reagents         | Failed   |  
| 180718_M00000_0151_000000000-BWFHW                               | 105217112 | Myeloid_DNA_Public_Data_MiSeq_11pM                 | Complete |  
...  
```

It is also possible to filter based on the `--date-field` of an entity using the `--newer-than` and `--older-than` flags. The default `--date-field` is the entity creation date (**DateCreated**). The example below lists all runs that were created in the past 5 weeks.

```
bs list run --newer-than 5w  
+------------------------------------+-----------+------------------------------------+----------+  
|                Name                |    Id     |           ExperimentName           |  Status  |  
+------------------------------------+-----------+------------------------------------+----------+  
| 180710_NS000000_0380_AH3FWGBGX5    | 103242144 | PhiX-Run                           | Complete |  
| 180718_M00000_0151_000000000-BWFHW | 105217112 | Myeloid_DNA_Public_Data_MiSeq_11pM | Complete |  
+------------------------------------+-----------+------------------------------------+----------+  
```

Available time suffixes: **s** (seconds), **m** (minutes), **h** (hours), **d** (days), **w** (weeks), **y** (years)

**Formatting**\
There are other options for formatting outputs that may be more useful as input into downstream commands or programs, such as comma-separated value (CSV) lists.

```
bs list runs --filter-field ExperimentName --filter-term NovaSeq -f csv  
Name,Id,ExperimentName,Status  
170220_A000000_0014_AHMWVDMCVY,23564552,NovaSeq: TruSeq Nano 550 (Replicates of NA12878),Failed  
```

Available output formats: **yaml**,**json**,**xml**,**csv**,**table** (default)

```
bs list runs -c bifx --filter-field ExperimentName --filter-term NovaSeq -f json  

[  
  {  
    "HrefBaseSpaceUI": "https://basespace.illumina.com/run/23564552/NovaSeq-TruSeq-Nano-550-Replicates-of-NA12878",  
    "Name": "170220_A00000_0014_AHMWVDMCVY",  
    "Id": "23564552",  
...  
  }  
]  
```

The option to output in JSON format is also available, and can provide much more information in a format easily accessible by many downstream programs.\
Above is the raw output and has been truncated, while below [output.json](https://confluence.illumina.com/download/attachments/440334512/output.json?version=2\&modificationDate=1592846944733\&api=v2) for the full output text.

```
[  
  {  
    "HrefBaseSpaceUI": "https://basespace.illumina.com/run/23564552/NovaSeq-TruSeq-Nano-550-Replicates-of-NA12878",  
    "Name": "170220_A00000_0014_AHMWVDMCVY",  
    "Id": "23564552",  
    "DateCreated": "2017-03-21T20:38:16Z",  
    "DateModified": "2019-09-19T16:58:48Z",  
    "DateUploadStarted": null,  
    "DateUploadCompleted": null,  
    "DateInstrumentStarted": "2017-03-21T20:38:14Z",  
    "DateInstrumentCompleted": "2017-03-24T12:16:07Z",  
    "Number": 0,  
    "UserOwnedBy": {  
      "Id": "9319322",  
      "Name": "Illumina Public Data",  
      "GravatarUrl": "https://secure.gravatar.com/avatar/c028aa9f7bb49e5c99efd2c6a329d8d6.jpg?s=20&d=mm&r=PG",  
      "DateLastActive": "",  
      "DateCreated": "0001-01-01T00:00:00.0000000Z"  
    },  
    "ExperimentName": "NovaSeq: TruSeq Nano 550 (Replicates of NA12878)",  
    "Status": "Failed",  
    "ReagentBarcode": "",  
    "FlowcellBarcode": "",  
    "Instrument": {  
      "InstrumentId": 0000000,  
      "Name": "DA-Test",  
      "SerialNumber": "DA-Test"  
    },  
    "InstrumentName": "DA-Test",  
    "InstrumentType": "NovaSeq6000",  
    "PlatformName": "NovaSeq",  
    "Workflow": "Generate FASTQ",  
    "NumCyclesRead1": 0,  
    "NumCyclesRead2": 0,  
    "NumCyclesIndex1": 0,  
    "NumCyclesIndex2": 0,  
    "SequencingStats": {  
      "Chemistry": "",  
      "ErrorRate": 0.381995,  
      "ErrorRateR1": 0.311466,  
      "ErrorRateR2": 0.452525,  
      "IntensityCycle1": 823.545,  
      "IsIndexed": true,  
      "MaxCycleCalled": 318,  
      "MaxCycleExtracted": 318,  
      "MaxCycleScored": 318,  
      "MinCycleCalled": 318,  
      "MinCycleExtracted": 318,  
      "MinCycleScored": 318,  
      "NonIndexedErrorRate": 0.381995,  
      "NonIndexedIntensityCycle1": 779.075,  
      "NonIndexedPercentAligned": 1.26232,  
      "NonIndexedPercentGtQ30": 92.4524,  
      "NonIndexedProjectedTotalYield": 1333.43,  
      "NonIndexedYieldTotal": 1333.43,  
      "NumCyclesIndex1": 8,  
      "NumCyclesIndex2": 8,  
      "NumCyclesRead1": 151,  
      "NumCyclesRead2": 151,  
      "NumLanes": 2,  
      "NumReads": 4,  
      "NumSurfaces": 2,  
      "NumSwathsPerLane": 1,  
      "NumTilesPerSwath": 88,  
      "PercentAligned": 1.26232,  
      "PercentGtQ30": 92.6168,  
      "PercentGtQ30R1": 95.6105,  
      "PercentGtQ30R2": 89.2943,  
      "PercentPf": 0.771596,  
      "PercentResynthesis": 69.8303,  
      "PhasingR1": 0.0937093,  
      "PhasingR2": 0.0713997,  
      "PrePhasingR1": 0.0738698,  
      "PrePhasingR2": 0.04491,  
      "ProjectedTotalYield": 1395.65,  
      "ReadsPfTotal": 17781898240,  
      "ReadsTotal": 23045603328,  
      "YieldTotal": 1395.65  
    },  
    "LaneAndQcStatus": "QcPassed",  
    "LimsStatus": "NoLims",  
    "TotalSize": 438164818891,  
    "IsFileDataDeleted": false,  
    "IsArchived": false  
  }  
]  
```

\
\
\ <br>

|                                                                                                                                                                                                                                                                                                                                                                 |
| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| *For any feedback or questions regarding this article (Illumina Knowledge Article #3682), contact Illumina Technical Support* [*techsupport@illumina.com*](mailto:techsupport@illumina.com?subject=Question%2FFeedback%20Regarding%20Illumina%20Knowledge%20Article%20#000003682%20-%20Software%20\&body=Dear%20Illumina%20Technical%20Support,%0D%0A%0D%0A)*.* |


---

# 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://knowledge.illumina.com/software/general/software-general-reference_material-list/000003682.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.
