BioInsight Platform Licensing
DRAGEN runs licensed through Illumina BioInsight Platform draw on a single BioInsight Credit (BIC) balance, whether DRAGEN runs inside the platform or on infrastructure you manage. Where you run DRAGEN determines only whether you need to provide an API key.
Illumina BioInsight Platform Core, or BaseSpace Sequence Hub (BSSH)
Nothing. The platform licenses each run for you.
DRAGEN FPGA Mode on AWS, Bring-Your-Own-License (BYOL)
A platform API key, provided to DRAGEN at runtime.
DRAGEN Software Mode, on your own CPU hardware
A platform API key, provided to DRAGEN at runtime.
DRAGEN Server (on-prem)
Not supported. DRAGEN Server uses licenses installed on the server using a separate prepaid quota. See DRAGEN Server Licensing.
If you run DRAGEN only inside Platform Core or BSSH, you do not need an API key, and you can skip Running DRAGEN on your own infrastructure and the sections after it.
Getting access
If you are new to Illumina BioInsight Platform, start with a free trial. If your organization is already on the platform, your Domain Administrator grants you access and your runs bill to the domain's existing subscription. See Software Billing.
How DRAGEN runs are charged
Your DRAGEN version determines how the DRAGEN licensing charge is calculated. DRAGEN Pricing charges each run based on the type of analysis and its analysis tier.
Illumina BioInsight Platform Core, including BSSH
DRAGEN Pricing
Legacy Gigabase Pricing
DRAGEN Software Mode, on your own CPU hardware BYOL
DRAGEN Pricing
Not available
DRAGEN FPGA Mode on AWS Public Cloud
DRAGEN Pricing
Legacy Gigabase Pricing
For both pricing models across every deployment, including legacy license credentials and the DRAGEN Server, see Licensing by deployment.
Compute and storage in Platform Core
The platform bills these separately from DRAGEN licensing. See the Platform Core pricing reference.
When you run DRAGEN on your own infrastructure, compute and storage are costs of your own cloud account or hardware, and only DRAGEN licensing is charged in BIC.
Reviewing your usage
All DRAGEN usage licensed through the platform, both in-platform runs and API key runs, is reported in the Illumina BioInsight Platform Usage Explorer rather than in DRAGEN output. The price of an individual in-platform analysis is also shown with that analysis in Platform Core.
Reconciling a run with its charge
On DRAGEN 4.5 and later, each run has a DRAGEN Run UUID. Look up that UUID in the DRAGEN Usage Report in the Usage Explorer to find the exact licensing event for the run.
DRAGEN records the UUID in .metadata.run_uuid of the unified JSON metrics file, <output-prefix>.metrics.json, in the output directory. DRAGEN 4.6 also prints the UUID to standard output and the run log.
dragen_lic does not report platform usage and rejects API keys with the error in Troubleshooting.
Running DRAGEN on your own infrastructure
An Illumina BioInsight Platform API key licenses DRAGEN on infrastructure you manage, and charges the same BIC balance as your in-platform runs. It is the recommended path for new BYOL deployments, and it covers two of them:
DRAGEN FPGA Mode on AWS BYOL, on an FPGA-enabled instance in your own cloud account. See DRAGEN FPGA Mode.
DRAGEN Software Mode, on commodity CPU hardware without an FPGA, such as generic cloud instances or High-Performance Computing (HPC) clusters. See DRAGEN Software Mode.
Prerequisites
DRAGEN contacts the license server, https://license.dragen.illumina.com, at runtime, so it needs outbound network access to it and cannot run fully offline. DRAGEN FPGA Mode on AWS BYOL also needs access to the instance metadata service, or saved instance identity documents. See Instance identity.
Illumina BioInsight Platform requirements
A new domain from a free trial satisfies the domain requirements for API key licensing, so there is nothing to check or change on the domain.
Existing domains created after August 4, 2026 also satisfy these domain requirements already. For an older domain, confirm both of the following:
A private domain. API key licensing does not work on a public domain, which is the most common reason an otherwise valid setup fails. Older BaseSpace Sequence Hub accounts are the usual case. For more details, see How to share BaseSpace Sequence Hub data between the public and private domains.
A qualifying subscription. Any current Illumina BioInsight Platform subscription (Free Trial, Pay-As-You-Go, or Savings Plan), Platform Core (formerly Illumina Connected Analytics, including the free Platform Core Basic tier), or Illumina Connected Software.
The API key has a requirement of its own, on every domain:
A DRAGEN API key. On the API Keys page, create a key scoped just for DRAGEN with the Generate DRAGEN API Key button. DRAGEN rejects unscoped keys created with the Generate button.
If you are unsure whether your domain qualifies, ask your Domain Administrator, check the Admin Console, or contact Illumina Customer Care.
Set up API key licensing
Generate a DRAGEN API key
On the API Keys page of your Illumina BioInsight Platform domain, click Generate DRAGEN API Key. See API Keys.
Provide the API key to DRAGEN
DRAGEN offers multiple methods for providing the API key. Which ones you can use depends on your DRAGEN version:
--api-key-file
In a file on disk
4.6 and later
DRAGEN_API_KEY_FILE
In a file on disk
4.6 and later
DRAGEN_API_KEY_VALUE
In the environment only
4.6 and later
License credentials file, passed with --lic-credentials
In a file on disk
4.2 and later
License credentials file, passed with DRAGEN_LICENSE_CREDENTIALS_FILE
In a file on disk
4.5 and later
On DRAGEN 4.2 through 4.5, use a license credentials file.
API key file and environment variables
The API key file must contain nothing but a single line with the key. Do not add a label, a key name, or any other content.
DRAGEN_API_KEY_FILE is equivalent to --api-key-file, and DRAGEN_API_KEY_VALUE takes the key itself with no file on disk.
License credentials file
A license credentials file is the only way to provide an API key on DRAGEN 4.2 through 4.5, and it also works on DRAGEN 4.6. Use the reserved user name IlluminaPlatform on the first line, and the API key on the second.
Pass the file with --lic-credentials, or on DRAGEN 4.5 and later, with the DRAGEN_LICENSE_CREDENTIALS_FILE environment variable.
Preview a charge before running
On DRAGEN 4.6, add --metering-preview to an otherwise complete command line. DRAGEN prints the application and analysis tier it estimates for that run, then exits, so nothing is analyzed and nothing is billed. The tier is resolved through Illumina BioInsight Platform, so --metering-preview needs the same API key and network access as the run itself.
The Features Utilized line records why a run landed in a given tier, and is the most useful part of the output when you need to reconcile a charge.
Troubleshooting
To use software mode (--sw-mode), an Illumina Connected API Key must be provided.
A Software Mode run found no key. It exits before analysis. Provide a key with one of the methods above.
ERROR: The --lic-server option is not supported for SW mode.
--lic-server passes a legacy user name and password, which Software Mode does not accept. It is also deprecated on every deployment, and DRAGEN 4.6 warns when it is used.
ERROR: --metering-preview is only available for Illumina Connected runs, but no Illumina Connected API key was found.
--metering-preview resolves the tier through the platform, so it needs the same key and network access as the run itself.
Illumina Connected API Keys are not supported with dragen_lic, please use the Illumina Connected Usage Explorer instead
dragen_lic reports installed prepaid licenses only. See Reviewing your usage.
Authentication Failed - API Key '<name>' is not scoped. DRAGEN only accepts API Keys scoped to DRAGEN. Please create an API Key with only DRAGEN scopes.
The key was created with the Generate button. Create a new key with Generate DRAGEN API Key button.
A run that fails licensing with a valid-looking key is usually a domain problem, or the key was not created with Generate DRAGEN API Key button. Check the Illumina BioInsight Platform requirements first, and that the key is a DRAGEN API key.
Last updated
Was this helpful?

