Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Element Biosciences Cloud Execution Service API
description: 'The Element Biosciences Cloud API provides programmatic access to data in
the Element Biosciences Cloud platform: instrument runs (sequencing and
multiomics), workflow executions, registered instruments, storage
connections, and the files those resources produce.
All paths are versioned under `/v1`.
## Authentication
Every request must include an API key in the `x-api-key` header. Create and
manage keys in the Element Biosciences Cloud console. Call `GET /v1/auth` to
confirm which tenant a key belongs to.
## Scopes
Each API key carries one or more scopes of the form
`resource:action[:resource_id]`, for example `runs:read`,
`executions:download`, or `storage:download:{connection_id}`. A request that
is authenticated but lacks the required scope fails with HTTP 403 and the
`INSUFFICIENT_SCOPE` reason. List endpoints transparently restrict results
to the resources a key is scoped to.
## Pagination
List endpoints are cursor-paginated. Set `page_size` to control the page
length and pass the `next_page_token` from one response as the `page_token`
of the next; an empty `next_page_token` indicates the last page.
## Errors
Errors return a JSON body with an integer `code`, a human-readable
`message`, and a `details` array. Each detail carries a machine-readable
`reason` (for example `RUN_NOT_FOUND` or `INVALID_API_KEY`) and the
`domain` `cloud-api.elembio.io`. The `request_id` in the detail metadata
matches the `X-Request-ID` response header; include it when reporting
problems.
'
version: 1.0.0
contact:
name: Element Biosciences
url: https://www.elembio.io
servers:
- url: https://cloud-api.usw2.elembio.io
security:
- apiKey: []
tags:
- name: ExecutionService
description: "ExecutionService provides access to workflow executions — runs of a\n bioinformatics workflow that process instrument data. Listing and reading\n execution metadata requires the \"executions:read\" scope; listing files and\n obtaining download credentials requires \"executions:download\"; retrieving\n logs requires \"executions:logs\"."
paths:
/v1/executions:
get:
tags:
- ExecutionService
summary: ListExecutions
description: "List executions accessible to the authenticated tenant, optionally\n filtered."
operationId: ExecutionService_ListExecutions
parameters:
- name: filter
in: query
description: "Search and filter expression. Space-separated `keyword:value` terms are\n ANDed together; bare text with no keyword searches all string fields. For\n date fields, replace the colon with a comparison operator (`>=`, `<=`,\n `>`, `<`, `!=`). List alternatives for one keyword with commas, e.g.\n `status:running,pending`. Dates accept ISO-8601 or relative offsets such\n as `24h`, `7d`, or `1mo`.\n\n Filterable keywords:\n\n - **String:** `name`, `input.run.id`, `input.run.name`, `input.run.instrument_name`, `input.execution.id`, `input.execution.name`, `flow.name`, `workflow.name`, `started_by`\n - **Enum:** `status`, `platform` (`aws_omics`, `seqera`, `dnanexus`, `catalyst`), `output.kind` (`fastq`, `bam`, `vcf`, `cram`, `parquet`)\n - **Date:** `time_created`, `time_started`, `time_completed`, `time_updated`\n\n Examples:\n\n - `workflow.name:bases2fastq status:running`\n - `platform:seqera output.kind:fastq time_completed>=24h`"
schema:
type: string
title: filter
description: "Search and filter expression. Space-separated `keyword:value` terms are\n ANDed together; bare text with no keyword searches all string fields. For\n date fields, replace the colon with a comparison operator (`>=`, `<=`,\n `>`, `<`, `!=`). List alternatives for one keyword with commas, e.g.\n `status:running,pending`. Dates accept ISO-8601 or relative offsets such\n as `24h`, `7d`, or `1mo`.\n\n Filterable keywords:\n\n - **String:** `name`, `input.run.id`, `input.run.name`, `input.run.instrument_name`, `input.execution.id`, `input.execution.name`, `flow.name`, `workflow.name`, `started_by`\n - **Enum:** `status`, `platform` (`aws_omics`, `seqera`, `dnanexus`, `catalyst`), `output.kind` (`fastq`, `bam`, `vcf`, `cram`, `parquet`)\n - **Date:** `time_created`, `time_started`, `time_completed`, `time_updated`\n\n Examples:\n\n - `workflow.name:bases2fastq status:running`\n - `platform:seqera output.kind:fastq time_completed>=24h`"
- name: pageSize
in: query
description: 'Maximum number of executions to return (default: 100, max: 1000)'
schema:
type: integer
title: page_size
format: int32
description: 'Maximum number of executions to return (default: 100, max: 1000)'
- name: pageToken
in: query
description: Token for pagination
schema:
type: string
title: page_token
description: Token for pagination
- name: includeTotalCount
in: query
description: If true, include total_count in the response (adds a count query)
schema:
type: boolean
title: include_total_count
description: If true, include total_count in the response (adds a count query)
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/elembio.cloud.v1.ListExecutionsResponse'
'400':
description: Bad request — the request was malformed or a parameter was invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized — the API key is missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden — the API key lacks the required scope.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not found — the requested resource does not exist or is not accessible.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v1/executions/{execution_id}/credentials:
get:
tags:
- ExecutionService
summary: GetExecutionDownloadCredentials
description: "Get temporary, read-only S3 credentials scoped to an execution's storage\n location. Use these for bulk or repeated downloads via the AWS CLI or SDK\n instead of per-object presigned URLs."
operationId: ExecutionService_GetExecutionDownloadCredentials
parameters:
- name: execution_id
in: path
description: The execution ID
required: true
schema:
type: string
title: execution_id
description: The execution ID
- name: prefix
in: query
description: "Optional path prefix within the execution to scope credentials to.\n Execution-relative, identical semantics to\n ListExecutionFilesRequest.prefix. \"..\" segments are rejected.\n When omitted, credentials are scoped to the whole execution (the\n execution root)."
schema:
type: string
title: prefix
description: "Optional path prefix within the execution to scope credentials to.\n Execution-relative, identical semantics to\n ListExecutionFilesRequest.prefix. \"..\" segments are rejected.\n When omitted, credentials are scoped to the whole execution (the\n execution root)."
- name: expirationSeconds
in: query
description: "Lifetime of the returned credentials, in seconds. Optional; defaults to\n 1 hour (when 0 or unset). Minimum 900s. Capped by AWS: up to 36h (129600s)\n for federation-token connections, or the role's MaxSessionDuration (12h\n typical) for role-backed connections. Values below the minimum or above the\n cap are rejected."
schema:
type: integer
title: expiration_seconds
format: int32
description: "Lifetime of the returned credentials, in seconds. Optional; defaults to\n 1 hour (when 0 or unset). Minimum 900s. Capped by AWS: up to 36h (129600s)\n for federation-token connections, or the role's MaxSessionDuration (12h\n typical) for role-backed connections. Values below the minimum or above the\n cap are rejected."
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/elembio.cloud.v1.GetExecutionDownloadCredentialsResponse'
'400':
description: Bad request — the request was malformed or a parameter was invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized — the API key is missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden — the API key lacks the required scope.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not found — the requested resource does not exist or is not accessible.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v1/executions/{execution_id}/files:
get:
tags:
- ExecutionService
summary: ListExecutionFiles
description: "List the files produced by an execution, drawn from the execution's\n storage location."
operationId: ExecutionService_ListExecutionFiles
parameters:
- name: execution_id
in: path
description: The execution ID
required: true
schema:
type: string
title: execution_id
description: The execution ID
- name: prefix
in: query
description: "Path prefix within the execution, e.g. \"visualization/\" or \"Stats/foo\".\n The execution is a self-contained namespace: paths do not include any\n bucket-level or workflow-level layout. Round-trips with File.path\n returned by this RPC. \"..\" segments are rejected.\n Optional: when omitted, lists the whole execution (the execution root)."
schema:
type: string
title: prefix
description: "Path prefix within the execution, e.g. \"visualization/\" or \"Stats/foo\".\n The execution is a self-contained namespace: paths do not include any\n bucket-level or workflow-level layout. Round-trips with File.path\n returned by this RPC. \"..\" segments are rejected.\n Optional: when omitted, lists the whole execution (the execution root)."
- name: recursive
in: query
description: "If true, list all files recursively under the prefix (default: true)\n If false, list only files and subdirectories at the current level"
schema:
type: boolean
title: recursive
description: "If true, list all files recursively under the prefix (default: true)\n If false, list only files and subdirectories at the current level"
- name: pageSize
in: query
description: 'Maximum number of files to return per page (default: 1000, max: 1000)'
schema:
type: integer
title: page_size
format: int32
description: 'Maximum number of files to return per page (default: 1000, max: 1000)'
- name: pageToken
in: query
description: Continuation token from previous response (passthrough from storage)
schema:
type: string
title: page_token
description: Continuation token from previous response (passthrough from storage)
- name: includeDownloadUrl
in: query
description: "If true, populate File.download_url (a presigned URL) on each returned\n file. Defaults to false. Set to true only when the caller intends to\n fetch file content from the response: generating presigned URLs has a\n per-object cost and the URLs themselves are credentials with a\n multi-hour lifetime. Use GetExecutionDownloadCredentials when\n long-lived bulk access is required."
schema:
type: boolean
title: include_download_url
description: "If true, populate File.download_url (a presigned URL) on each returned\n file. Defaults to false. Set to true only when the caller intends to\n fetch file content from the response: generating presigned URLs has a\n per-object cost and the URLs themselves are credentials with a\n multi-hour lifetime. Use GetExecutionDownloadCredentials when\n long-lived bulk access is required."
- name: downloadUrlExpirationSeconds
in: query
description: "Lifetime of the presigned download_url, in seconds. Optional; defaults to\n 1 hour. Only applies when include_download_url = true. Max 7 days."
schema:
type: integer
title: download_url_expiration_seconds
format: int32
description: "Lifetime of the presigned download_url, in seconds. Optional; defaults to\n 1 hour. Only applies when include_download_url = true. Max 7 days."
- name: includeDownloadChecksum
in: query
description: "If true, presign each download_url with S3 ChecksumMode=ENABLED so the\n object's stored checksum is returned on the GET (in the\n x-amz-checksum-<algo> response header) and a client can verify download\n integrity in a single streaming pass. Defaults false; has no effect unless\n include_download_url = true. When enabled the presigned URL signs the\n x-amz-checksum-mode request header, so the fetch MUST send\n x-amz-checksum-mode:ENABLED — a plain GET that omits it fails with HTTP\n 403. Best-effort: objects stored without a checksum return none.\n\n Applies only to AWS S3-backed storage connections; other storage backends\n do not presign S3 GETs and silently ignore this field."
schema:
type: boolean
title: include_download_checksum
description: "If true, presign each download_url with S3 ChecksumMode=ENABLED so the\n object's stored checksum is returned on the GET (in the\n x-amz-checksum-<algo> response header) and a client can verify download\n integrity in a single streaming pass. Defaults false; has no effect unless\n include_download_url = true. When enabled the presigned URL signs the\n x-amz-checksum-mode request header, so the fetch MUST send\n x-amz-checksum-mode:ENABLED — a plain GET that omits it fails with HTTP\n 403. Best-effort: objects stored without a checksum return none.\n\n Applies only to AWS S3-backed storage connections; other storage backends\n do not presign S3 GETs and silently ignore this field."
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/elembio.cloud.v1.ListExecutionFilesResponse'
'400':
description: Bad request — the request was malformed or a parameter was invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized — the API key is missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden — the API key lacks the required scope.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not found — the requested resource does not exist or is not accessible.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v1/executions/{execution_id}/logs:
get:
tags:
- ExecutionService
summary: GetExecutionLogs
description: "Get the log and error output from the compute platform for an execution.\n Requires the \"executions:logs\" scope."
operationId: ExecutionService_GetExecutionLogs
parameters:
- name: execution_id
in: path
description: The execution ID
required: true
schema:
type: string
title: execution_id
description: The execution ID
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/elembio.cloud.v1.GetExecutionLogsResponse'
'400':
description: Bad request — the request was malformed or a parameter was invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized — the API key is missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden — the API key lacks the required scope.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not found — the requested resource does not exist or is not accessible.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v1/executions/{id}:
get:
tags:
- ExecutionService
summary: GetExecution
description: Get a single execution by its ID.
operationId: ExecutionService_GetExecution
parameters:
- name: id
in: path
description: The unique identifier of the execution
required: true
schema:
type: string
title: id
description: The unique identifier of the execution
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/elembio.cloud.v1.GetExecutionResponse'
'400':
description: Bad request — the request was malformed or a parameter was invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized — the API key is missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden — the API key lacks the required scope.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not found — the requested resource does not exist or is not accessible.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
elembio.cloud.v1.GetExecutionResponse:
type: object
properties:
execution:
title: execution
$ref: '#/components/schemas/elembio.cloud.v1.Execution'
title: GetExecutionResponse
additionalProperties: false
description: Response containing a single execution with full details
elembio.cloud.v1.GetExecutionLogsResponse:
type: object
properties:
error:
type: string
title: error
description: Error output from the compute platform (if any)
log:
type: string
title: log
description: Full execution log from the compute platform (if any)
title: GetExecutionLogsResponse
additionalProperties: false
description: Response containing execution logs
elembio.cloud.v1.ExecutionReference:
type: object
properties:
id:
type: string
title: id
name:
type: string
title: name
workflowName:
type: string
title: workflow_name
title: ExecutionReference
additionalProperties: false
description: Reference to an upstream execution
elembio.cloud.v1.S3Credentials:
type: object
properties:
region:
type: string
title: region
description: 'AWS region. Example: "us-west-2".'
bucket:
type: string
title: bucket
description: S3 bucket name.
prefix:
type:
- string
- 'null'
title: prefix
description: "Key prefix the credentials are scoped to — bucket-absolute, since\n this value is consumed directly by the AWS CLI / SDK. Distinct from\n the request-side `prefix`, which is connection-relative."
accessKeyId:
type: string
title: access_key_id
description: Temporary AWS access key ID
secretAccessKey:
type: string
title: secret_access_key
description: Temporary AWS secret access key
sessionToken:
type: string
title: session_token
description: STS session token
expiration:
title: expiration
description: When the credentials expire
$ref: '#/components/schemas/google.protobuf.Timestamp'
title: S3Credentials
additionalProperties: false
description: "Temporary read-only AWS S3 credentials scoped to a bucket and prefix.\n Use with the AWS CLI, AWS SDK, or any S3-compatible tool. The credentials\n expire at the time given by expiration; request new credentials when they\n near expiry."
elembio.cloud.v1.ListExecutionsResponse:
type: object
properties:
executions:
type: array
items:
$ref: '#/components/schemas/elembio.cloud.v1.Execution'
title: executions
description: List of executions
nextPageToken:
type: string
title: next_page_token
description: Token for the next page (empty if no more results)
previousPageToken:
type: string
title: previous_page_token
description: Token for the previous page (empty if on first page)
totalCount:
type:
- integer
- 'null'
title: total_count
format: int32
description: Total number of executions matching the filter (only if include_total_count was true)
title: ListExecutionsResponse
additionalProperties: false
description: Response containing a list of executions
elembio.cloud.v1.ExecutionInput:
type: object
oneOf:
- type: object
properties:
execution:
title: execution
description: Upstream execution reference
$ref: '#/components/schemas/elembio.cloud.v1.ExecutionReference'
title: execution
required:
- execution
- type: object
properties:
run:
title: run
description: Instrument run reference
$ref: '#/components/schemas/elembio.cloud.v1.RunReference'
title: run
required:
- run
title: ExecutionInput
description: Input data source for the execution
Error:
type: object
description: Error response returned by all endpoints when a request fails.
properties:
code:
type: integer
description: Numeric status code corresponding to the HTTP response status
message:
type: string
description: Human-readable error message
details:
type: array
description: Structured error details with machine-readable reason codes
items:
$ref: '#/components/schemas/ErrorDetail'
required:
- code
- message
examples:
- code: 404
message: Run not found.
details:
- reason: RUN_NOT_FOUND
domain: cloud-api.elembio.io
metadata:
request_id: 550e8400-e29b-41d4-a716-446655440000
- code: 401
message: Invalid API key.
details:
- reason: INVALID_API_KEY
domain: cloud-api.elembio.io
metadata:
request_id: 550e8400-e29b-41d4-a716-446655440001
elembio.cloud.v1.File:
type: object
properties:
path:
type: string
title: path
description: "Path within the namespace of the RPC that returned this file.\n Namespace is the run / execution / storage connection, depending on\n the RPC. Round-trips with the request prefix: paste any returned\n path back into a subsequent --prefix to drill in.\n Example: \"A24-S2/run-001/manifest.json\"."
name:
type: string
title: name
description: "Filename portion of the path (convenience field)\n Example: \"sample1.fastq.gz\""
size:
type:
- integer
- string
title: size
format: int64
description: Size in bytes
lastModified:
title: last_modified
description: Last modification timestamp
$ref: '#/components/schemas/google.protobuf.Timestamp'
uri:
type: string
title: uri
description: "Full URI for the object — always storage-absolute, regardless of the\n RPC. Use this for direct backend access (S3 SDK, etc.).\n Example: \"s3://bucket-name/runs/run-123/outputs/sample1.fastq.gz\""
downloadUrl:
type: string
title: download_url
description: "Pre-signed URL for downloading this object over HTTP GET.\n Populated only when the request set include_download_url = true; empty\n otherwise. The URL is a short-lived credential — fetch promptly and do\n not persist it. For bulk or repeated downloads, request download\n credentials instead."
storageClass:
type:
- string
- 'null'
title: storage_class
description: "Storage class of the object. Examples: \"STANDARD\", \"GLACIER\",\n \"DEEP_ARCHIVE\"."
title: File
additionalProperties: false
description: A File represents an object in cloud storage.
elembio.cloud.v1.Flow:
type: object
properties:
id:
type: string
title: id
name:
type: string
title: name
title: Flow
additionalProperties: false
description: Flow represents a configured workflow
elembio.cloud.v1.RunReference:
type: object
properties:
id:
type: string
title: id
name:
type: string
title: name
instrumentName:
type: string
title: instrument_name
kitType:
type: string
title: kit_type
description: "The run's kit. For multiomics runs, one of the multiomics kit values\n (`cytoprofiling`, `direct_in_sample_sequencing`, `antibody_screening`,\n `tissue`, `protein_screening`); for sequencing runs, the sequencing kit."
runType:
type: string
title: run_type
description: '"sequencing" or "multiomics"'
title: RunReference
additionalProperties: false
description: Reference to an instrument run
ErrorDetail:
type: object
description: Structured error detail with a machine-readable reason code.
properties:
'@type':
type: string
description: Type identifier for this error detail
reason:
type: string
description: 'Machine-readable error code identifying the specific failure
(e.g. RUN_NOT_FOUND, INVALID_API_KEY, INSUFFICIENT_SCOPE).
'
examples:
- RUN_NOT_FOUND
- INVALID_API_KEY
- MISSING_API_KEY
- INSUFFICIENT_SCOPE
- INTERNAL_ERROR
domain:
type: string
description: Identifies the system that generated the error
const: cloud-api.elembio.io
metadata:
type: object
description: Additional context for the error
properties:
request_id:
type: string
description: Request ID matching the X-Request-ID response header
required:
- reason
- domain
elembio.cloud.v1.Execution:
type: object
properties:
id:
type: string
title: id
description: Unique identifier for the execution
name:
type: string
title: name
description: Human-readable name of the execution
status:
title: status
description: Current status of the execution
$ref: '#/components/schemas/elembio.cloud.v1.ExecutionStatus'
statusDescription:
type: string
title: status_description
description: Detailed status description from the compute platform
platform:
type: string
title: platform
description: "Compute platform running this execution.\n Possible values: \"aws_omics\", \"seqera\", \"dnanexus\", \"catalyst\"."
workflow:
title: workflow
description: Workflow information
$ref: '#/components/schemas/elembio.cloud.v1.Workflow'
flow:
title: flow
description: Flow (configured workflow) used for this execution
$ref: '#/components/schemas/elembio.cloud.v1.Flow'
inputs:
type: array
items:
$ref: '#/components/schemas/elembio.cloud.v1.ExecutionInput'
title: inputs
description: Input data sources
output:
title: output
description: Output location and content types
$ref: '#/components/schemas/elembio.cloud.v1.Output'
startedBy:
title: started_by
description: User who started the execution
$ref: '#/components/schemas/elembio.cloud.v1.UserSummary'
timeCreated:
title: time_created
description: Timestamps
$ref: '#/components/schemas/google.protobuf.Timestamp'
timeStarted:
oneOf:
- $ref: '#/components/schemas/google.protobuf.Timestamp'
- type: 'null'
title: time_started
timeCompleted:
oneOf:
- $ref: '#/components/schemas/google.protobuf.Timestamp'
- type: 'null'
title: time_completed
errorMessage:
type:
- string
- 'null'
title: error_message
description: "Human-readable error summary describing why the execution failed.\n Use GetExecutionLogs for full provider error and log output."
title: Execution
additionalProperties: false
description: An Execution represents a workflow run processing instrument data
elembio.cloud.v1.Workflow:
type: object
properties:
name:
type: string
title: name
version:
type: string
title: version
title: Workflow
additionalProperties: false
description: Workflow information
google.proto
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/element-biosciences/refs/heads/main/openapi/element-biosciences-executionservice-api-openapi.yml