Skip to main content

Illumina BaseSpace Data Source

The Illumina BaseSpace Sequence Hub connector enables you to ingest genomics data — including projects, samples, runs, analyses, and sequencing files — directly into Nexla for downstream processing, reporting, and integration with other data systems. Follow the instructions below to create a new data flow that ingests data from an Illumina BaseSpace source in Nexla.
illumina_basespace_api.png

Illumina BaseSpace

Create a New Data Flow​

  1. To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Then, select the desired flow type from the list, and click the Create button.

  2. Select the Illumina BaseSpace connector tile from the list of available connectors. Then, select the credential that will be used to connect to the Illumina BaseSpace instance, and click Next; or, create a new Illumina BaseSpace credential for use in this flow.

  3. In Nexla, Illumina BaseSpace data sources can be created using pre-built endpoint templates, which expedite source setup for common Illumina BaseSpace endpoints. Each template is designed specifically for the corresponding Illumina BaseSpace endpoint, making data source setup easy and efficient.
    • To configure this source using a template, follow the instructions in Configure Using a Template.

    Illumina BaseSpace sources can also be configured manually, allowing you to ingest data from Illumina BaseSpace endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
    • To configure this source manually, follow the instructions in Configure Manually.

Configure Using a Template​

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Illumina BaseSpace endpoints. Each template is designed specifically for the corresponding Illumina BaseSpace endpoint, making data source setup easy and efficient.

Endpoint Settings​

  • Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.

    List Projects

    Returns a list of projects for the current authenticated user. Use this endpoint to enumerate all accessible BaseSpace projects for downstream sample and run discovery.

    • Sends a GET request to /v1pre3/users/current/projects and returns all projects accessible to the authenticated user.
    • Response data is nested under $.Response.Items[*]; each element represents a single project record.

    The BaseSpace API uses the authenticated user's access token scope to determine which projects are visible. Ensure your credential has the appropriate read permissions for the projects you intend to ingest.

    List Runs

    Returns a list of sequencing runs for the current authenticated user. Use this endpoint to track run status, metadata, and quality metrics across your sequencing operations.

    • Sends a GET request to /v1pre3/users/current/runs and returns all sequencing runs for the authenticated user.
    • Response data is nested under $.Response.Items[*]; each element represents a single run record including status, instrument, and date information.

    Run records include metadata such as instrument type, run status, and creation date. These fields are useful for filtering and routing data in downstream Nexla flows.

    List Samples

    Returns a list of samples for a specific BaseSpace project. Use this endpoint to retrieve sample-level metadata for quality assessment, LIMS integration, or downstream bioinformatics workflows.

    • Sends a GET request to /v1pre3/projects/{projectId}/samples and returns all samples within the specified project.
    • Response data is nested under $.Response.Items[*]. Configure the following parameters: Project ID — the BaseSpace project ID from which samples will be listed.

    Project IDs can be retrieved using the List Projects endpoint. Consider using a Nexla lookup to dynamically pass project IDs into this endpoint for multi-project ingestion workflows.

    List Sample Files

    Returns a list of files associated with a specific sample. Use this endpoint to enumerate FASTQ files or other sequencing output files for a given sample.

    • Sends a GET request to /v1pre3/samples/{sampleId}/files and returns all files associated with the specified sample.
    • Response data is nested under $.Response.Items[*]. Configure the following parameters: Sample ID — the BaseSpace sample ID whose files will be listed.

    Sample IDs can be retrieved using the List Samples endpoint. File records include download URLs that can be used in downstream processing steps.

    List Run Files

    Returns a list of files associated with a specific sequencing run. Use this endpoint to retrieve run-level output files such as run logs, InterOp data, and quality metrics.

    • Sends a GET request to /v1pre3/runs/{runId}/files and returns all files associated with the specified run.
    • Response data is nested under $.Response.Items[*]. Configure the following parameters: Run ID — the BaseSpace run ID whose files will be listed.

    Run IDs can be retrieved using the List Runs endpoint. Run files may be large; use file metadata (size, type) returned in the response to filter before initiating any download steps.

    List App Sessions

    Returns a list of application sessions for the current authenticated user. Use this endpoint to monitor the status of launched BaseSpace applications and analysis pipelines.

    • Sends a GET request to /v1pre3/users/current/appsessions and returns all app sessions for the authenticated user.
    • Response data is nested under $.Response.Items[*]; each element represents a single app session including its status and associated application details.

    App session status values (e.g., Running, Complete, Aborted) can be used to filter records and trigger conditional logic in downstream Nexla flow steps.

    List App Results

    Returns a list of application results for a specific app session. Use this endpoint to retrieve analysis output metadata produced by BaseSpace applications.

    • Sends a GET request to /v1pre3/appsessions/{appSessionId}/appresults and returns all app results for the specified session.
    • Response data is nested under $.Response.Items[*]. Configure the following parameters: App Session ID — the BaseSpace app session ID whose results will be listed.

    App session IDs can be retrieved using the List App Sessions endpoint. App result records contain references to the output files, which can be retrieved using the List App Result Files endpoint.

    List App Result Files

    Returns a list of files associated with specific app results. Use this endpoint to enumerate analysis output files generated by BaseSpace applications for downstream processing or archival.

    • Sends a GET request to /v1pre3/appresults/{appResultId}/files and returns all files associated with the specified app result.
    • Response data is nested under $.Response.Items[*]. Configure the following parameters: App Result ID — the BaseSpace app result ID whose files will be listed.

    App result IDs can be retrieved using the List App Results endpoint. File records include pre-signed download URLs valid for a limited time period.

    Cross-resource search across samples, runs, projects, genomes

    Performs a cross-resource search across samples, runs, projects, genomes, app results, and files using a query string. Use this endpoint to discover resources across multiple BaseSpace entity types in a single call.

    • Sends a GET request to /v1pre3/search with scope, query, and offset parameters. Response data is nested under $.Response.Items[*].
    • Configure the following parameters: Scope — the resource type to search (e.g., Projects, Samples, Runs); Query — the search string; Offset — starting position for paginated results.

    Use the Scope parameter to narrow search results to specific resource types. Combining this endpoint with the Offset parameter allows paginated retrieval of large search result sets.

    Retrieve File Metadata and Download URL

    Retrieves metadata and a pre-signed download URL for a single file. Use this endpoint to obtain time-limited download URLs for specific BaseSpace files.

    • Sends a GET request to /v1pre3/files/{fileId} and returns metadata and a pre-signed download URL for the specified file.
    • Response data is returned at the root path $. Configure the following parameters: File ID — the BaseSpace file ID for which to retrieve metadata and a download URL.

    Pre-signed download URLs returned by this endpoint are time-limited. Retrieve and use them promptly within your data flow to avoid expiration errors.

    List Reference Genomes

    Lists reference genomes available in BaseSpace, including build, organism, and other metadata. Use this endpoint to retrieve genome reference data for annotation or pipeline configuration workflows.

    • Sends a GET request to /v1pre3/genomes with optional sort parameters. Response data is nested under $.Response.Items[*].
    • Configure the following parameters: Sort By — the field to sort results by; Sort Direction — ascending or descending sort order.

    Genome records include organism name, build identifier, and species information. This endpoint is useful for populating reference lookup tables used in other BaseSpace data flows.

    Retrieve Single Project by ID

    Retrieves a single project by its BaseSpace project ID. Use this endpoint when you need complete metadata for a specific project rather than a full list.

    • Sends a GET request to /v1pre3/projects/{projectId} and returns the full project record.
    • Response data is returned at the root path $. Configure the following parameters: Project ID — the BaseSpace project ID to retrieve.

    This endpoint returns a single object rather than an array. Use $ as the path to data rather than $.Response.Items[*] when configuring this endpoint.

    List App Results Under a Project

    Lists all app results directly under a project, without going through app sessions. Use this endpoint to retrieve analysis outputs at the project level for project-wide reporting.

    • Sends a GET request to /v1pre3/projects/{projectId}/appresults and returns app results for the specified project. Response data is nested under $.Response.Items[*].
    • Configure the following parameters: Project ID — the BaseSpace project ID; Sort By — optional sort field; Sort Direction — optional sort order; Offset — starting position for paginated results.

    Use the Offset parameter to paginate through large numbers of app results within a project. The Sort By and Sort Direction parameters allow you to retrieve the most recent results first.

    Retrieve Single Run by ID

    Retrieves a single sequencing run by its BaseSpace run ID. Use this endpoint to fetch complete run metadata for a specific run.

    • Sends a GET request to /v1pre3/runs/{runId} and returns the full run record.
    • Response data is returned at the root path $. Configure the following parameters: Run ID — the BaseSpace run ID to retrieve.

    This endpoint returns a single object. Use $ as the path to data. Run IDs can be retrieved from the List Runs endpoint.

    Retrieve Single Sample by ID

    Retrieves a single sample by its BaseSpace sample ID. Use this endpoint when you need complete metadata for a specific sample.

    • Sends a GET request to /v1pre3/samples/{sampleId} and returns the full sample record.
    • Response data is returned at the root path $. Configure the following parameters: Sample ID — the BaseSpace sample ID to retrieve.

    This endpoint returns a single object. Use $ as the path to data. Sample IDs can be retrieved from the List Samples endpoint.

    Retrieve Current User Profile

    Retrieves the currently authenticated user's profile and permission scope. Use this endpoint to validate credentials, inspect access scopes, or retrieve the current user ID for use in other API calls.

    • Sends a GET request to /v1pre3/users/current and returns the authenticated user's profile information.
    • Response data is returned at the root path $. No additional parameters are required.

    This endpoint is useful for verifying that your BaseSpace credential is correctly configured and has the expected permission scopes before building more complex data flows.

Endpoint Testing​

Once the selected endpoint template has been configured, Nexla can retrieve a sample of the data that will be fetched according to the current settings. This allows users to verify that the source is configured correctly before saving.

  • To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

  • If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Configure Manually​

Illumina BaseSpace sources can also be configured to ingest data from any valid BaseSpace API endpoint. Configuration options allow you to fully customize the source to suit any use case — including using chained API calls to fetch data from multiple endpoints or applying custom request parameters.

First, select the method that will be used for calls to the Illumina BaseSpace API from the Method pulldown menu. The most common methods are:

  • GET: For retrieving data such as projects, samples, runs, analyses, and files from the BaseSpace API

  • POST: For sending data to the API or triggering actions

API Endpoint URL​

  1. Enter the URL of the Illumina BaseSpace API endpoint from which this source will fetch data in the Set API URL field. This should be the complete URL including the protocol (https://) and any required path parameters.

    The BaseSpace API is available at two base URLs:

    • Version 1 (v1pre3): https://api.basespace.illumina.com/v1pre3/

    • Version 2: https://api.basespace.illumina.com/v2/

    Common BaseSpace API endpoints include:

    • https://api.basespace.illumina.com/v2/projects — Lists all projects accessible with your access token

    • https://api.basespace.illumina.com/v2/runs — Lists all sequencing runs

    • https://api.basespace.illumina.com/v2/biosamples — Lists all biosamples

    • https://api.basespace.illumina.com/v2/datasets — Lists all datasets

    • https://api.basespace.illumina.com/v1pre3/users/current/projects — Lists all projects for the authenticated user

    • https://api.basespace.illumina.com/v1pre3/samples/{'{sampleId}'} — Retrieves details for a specific sample

Ensure the API endpoint URL is correct and accessible with your current credentials. You can verify the endpoint using the Test button after configuring the URL. For a complete list of available endpoints and parameters, refer to the BaseSpace V2 API Reference and BaseSpace V1 API Reference.

Date/Time Macros (API URL)​

Optional

Optionally, the API URL can be customized using macros—all macros added to the API URL will be converted into values when Nexla executes the API call. Macros are dynamic placeholders that allow you to create flexible API endpoints that can adapt to different time periods or data requirements.

Date/time macros are particularly useful for BaseSpace endpoints that support date-range filtering, such as filtering runs or analyses created within a specific time window. Check the BaseSpace API documentation for the date filter parameters supported by each endpoint.

  1. To add a macro, type { at the appropriate position in the API URL (within the Set API URL field), and select the desired macro from the dropdown list.

    • {now} – The current datetime
    • {now-1} – The datetime one time unit before the current datetime
    • {now+1} – The datetime one time unit after the current datetime
    • custom – Datetime macros can reference any number of time units before or after the current datetime—for example, enter (now-4) to indicate the datetime four time units before the current datetime

  2. Select the format that will be applied to datetime macros from the Date Format for Date/Time Macro pulldown menu. This format will be applied to the base datetime value of the macro—i.e., the value of {now} in {now-1}.

  3. Select the datetime unit that will be used to perform mathematical operations in the included macro(s) from the Time Unit for Operations pulldown menu—for example, for the macro {now-1}, when Day is selected, {now-1} will be converted to the datetime one day before the current datetime.

Lookup-Based Macros (API URL)​

Optional

Column values from existing lookups can also be included as macros in the API URL. Lookup-based macros allow you to reference data from previously configured data sources or lookups, enabling dynamic API endpoints that can adapt based on existing data.

Lookup-based macros are useful for BaseSpace integrations where you need to dynamically reference project IDs, sample IDs, run IDs, or other identifiers retrieved from a prior data source in your Nexla environment.

  1. To include a lookup column value macro, select the relevant lookup from the Add Lookups to Supported Macros pulldown menu.

  2. Type { at the appropriate position in the API URL, and select the lookup column-based macro from the dropdown list. Lookup-based macros are automatically populated into the macro list when a lookup is selected in the Add Lookups to Supported Macros pulldown menu.

Path to Data​

Optional

If only a subset of the data returned by the API endpoint is needed, you can designate the part of the response that should be included in the Nexsets produced from this source by specifying the path to the relevant data within the response. This is particularly useful when API responses contain metadata, pagination information, or other data that you don't need for your analysis.

For example, BaseSpace API responses typically wrap the relevant data records inside an Items array within a Response object. By specifying the path to the Items array, you can configure Nexla to treat each element of that array as a record.

Path to Data is essential when working with BaseSpace API responses, which consistently use a nested response structure. For most BaseSpace endpoints, the path to relevant data is $.Response.Items[*].

  • To specify which data should be treated as relevant in responses from this source, enter the path to the relevant data in the Set Path to Data in Response field.

    • For responses in JSON format, enter the JSON path that points to the object or array that should be treated as relevant data. JSON paths use dot notation (e.g., $.Response.Items[*] to access the Items array within the Response object in BaseSpace API responses).
    Path to Data Example:

    For a BaseSpace API response that returns a list of projects with the structure {"Response": {"Items": [...], "TotalCount": 10}}, enter $.Response.Items[*] as the path to treat each project in the array as a separate record.

Autogenerate Path Suggestions​

Nexla can also autogenerate data path suggestions based on the response from the API endpoint. These suggested paths can be used as-is or modified to exactly suit your needs.

  • To use this feature, click the Test button next to the Set API URL field to fetch a sample response from the API endpoint. Suggested data paths generated based on the content & format of the response will be displayed in the Suggestions box below the Set Path to Data in Response field.

  • Click on a suggestion to automatically populate the Set Path to Data in Response field with the corresponding path. The populated path can be modified directly within the field if further customization is needed.

    PathSuggestions.png

Metadata​

If metadata is included in the response but is located outside of the defined path to relevant data, you can configure Nexla to include this data as common metadata in each record. This is useful when you want to preserve important contextual information that applies to all records but isn't part of the main data array.

For example, BaseSpace API responses include a Response object containing both an Items array (the main data records) and fields such as TotalCount and DisplayedCount. If you specify $.Response.Items[*] as the path to relevant data, you can additionally specify a path to the Response object to preserve summary metadata alongside each record.

Metadata paths are particularly useful when you want to preserve context such as the total record count or pagination information from the BaseSpace API response alongside each record in the generated Nexset.

  • To specify the location of metadata that should be included with each record, enter the path to the relevant metadata in the Path to Metadata in Response field.

    • For responses in JSON format, enter the JSON path to the object or array that contains the metadata (e.g., $.Response to include top-level response fields such as TotalCount).

Request Headers​

Optional

  • If Nexla should include any additional request headers in API calls to this source, enter the headers & corresponding values as comma-separated pairs in the Request Headers field (e.g., header1:value1,header2:value2). Additional headers are often required for API versioning, content type specifications, or custom requirements.

    You do not need to include the x-access-token authentication header — Nexla automatically includes your BaseSpace access token from the configured credential with every API request. Common headers like Authorization and Content-Type are handled automatically based on your credential configuration.

Endpoint Testing​

After configuring all settings for the selected endpoint, Nexla can retrieve a sample of the data that will be fetched according to the current configuration. This allows users to verify that the source is configured correctly before saving.

  • To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

  • If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Save & Activate the Source​

  1. Once all of the relevant steps in the above sections have been completed, click the Create button in the upper right corner of the screen to save and create the new Illumina BaseSpace data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.