Geoseeq API Client


GeoSeeq includes a Python-based command line tool. You can find the source code of this tool and more documentation on GitHub.


Install from PyPi

pip install geoseeq

Install from source

Download this directory and run python setup.py install

Using the Command Line

Run the command line by typing geoseeq into a terminal prompt. See available options by adding --help

$ geoseeq --help

Using an API token

You will need an API token to interact with GeoSeeq for many tasks. You can get this token by logging into the GeoSeeq Portal, going to your user profile, and clicking the "Tokens" tab.

Once you have a token, you will need to configure the geoseeq command line tool. You will be prompted to set a profile name, an endpoint, and your api token. You can leave the profile name and endpoint blank. You should input the token you got from the GeoSeeq portal. Finally, the config tool will ask you to confirm that you have read the end use license agreement which can be found here.

$ geoseeq config Set custom profile name? (Leave blank for default) []: Enter the URL to use for GeoSeeq (Most users can use the default) [https://backend.geoseeq.com]: Enter your GeoSeeq API token: Have you read and accepted the GeoSeeq End User License Agreement? Use `geoseeq eula show` to view the EULA. [y/N]:

Example Commands

You can find more command line examples in docs/

Download Short Read Sequencing data from one sample in a project as a set of FASTQ files

This command will download data from this project.

$ geoseeq download sample-results --module-name "short_read::paired_end" GeoSeeq "Example CLI Project" "s1"

Uploading sequencing data


GeoSeeq can automatically group fastq files into samples according to their
sample name, read number, and lane number. It supports paired-end, single-end,
and nanopore reads.

Assume you have data from a single-ended sequencing run stored as fastq files:

  • Sample1_L1_R1.fastq.gz

  • Sample1_L1_R2.fastq.gz

  • Sample1_L2_R1.fastq.gz

  • Sample1_L2_R2.fastq.gz

You can upload these files to GeoSeeq using the command line. This example will upload 32 files in parallel:

GeoSeeq will automatically create a new sample named Sample1 if it does not already exist.

This command would upload data to this project. Since only organization members can upload data, you must replace GeoSeeq with your organization name.

Note: You will need to have an API token set to use this command (see above)

Using the Python API in a program

Please see geoseeq_api/cli/download.py for examples of downloading data using the Python API directly.



Some terms have changed in GeoSeeq since this package was written. The command line tool and code may contain references to old names.

Old Name

New Name

Old Name

New Name

Sample Group



defunct, this concept is no longer used

Analysis Result

Result Folder

Analysis Result Field

Result File

License and Credits

GeoSeeq is built and maintained by Biotia

The GeoSeeq API client is licensed under the MIT license.


Rest API


GeoSeeq supports a RESTful API for users to interact with. This API may be used directly with tools like CURL or accessed through the officially supported Python library.

Swagger Documentation

Swagger documentation for the RESTful API may be found here.