Skip to content

client

Core module for oqtopus-client.

Classes:

  • OqtopusClient

    Synchronous public client; internal HTTP calls are executed asynchronously.

OqtopusClient

OqtopusClient(
    config: OqtopusConfig | None = None,
    default_headers: Mapping[str, str] | None = None,
    user_agent: str | None = None,
)

Synchronous public client; internal HTTP calls are executed asynchronously.

Parameters:

  • config

    (Optional, default: None ) –

    Client configuration bundle. If omitted, OqtopusConfig.from_file() is used. In normal mode, the resolved config must provide a non-empty base_url.

  • default_headers

    (Optional, default: None ) –

    Additional headers merged into every request.

  • user_agent

    (Optional, default: None ) –

    Custom User-Agent header value.

Methods:

cancel_job

cancel_job(job_id: str) -> SuccessSuccessResponse

Cancel a job by id.

Parameters:

  • job_id

    (Required) –

    Target job ID to cancel.

Returns:

  • SuccessSuccessResponse

    Success response from the API.

create_api_token

create_api_token() -> ApiTokenApiToken

Create an API token.

Returns:

  • ApiTokenApiToken

    The created API token payload.

delete_api_token

delete_api_token() -> None

Delete current API token.

delete_job

delete_job(job_id: str) -> SuccessSuccessResponse

Delete a job by id.

Parameters:

  • job_id

    (Required) –

    Target job ID to delete.

Returns:

  • SuccessSuccessResponse

    Success response from the API.

get_announcement

get_announcement(
    announcement_id: int,
) -> AnnouncementsGetAnnouncementResponse

Get one announcement by id.

Parameters:

  • announcement_id

    (Required) –

    Target announcement ID.

Returns:

  • AnnouncementsGetAnnouncementResponse

    The requested announcement payload.

get_announcements_list

get_announcements_list() -> (
    AnnouncementsGetAnnouncementsListResponse
)

List service announcements.

Returns:

  • AnnouncementsGetAnnouncementsListResponse

    Announcements list returned by the API.

get_api_token

get_api_token() -> ApiTokenApiTokenStatus

Get API token status.

Returns:

  • ApiTokenApiTokenStatus

    The current API token status payload.

get_api_token_status

get_api_token_status() -> ApiTokenApiTokenStatus

Get API token status.

Returns:

  • ApiTokenApiTokenStatus

    The current API token status payload.

get_device

get_device(device_id: str) -> OqtopusDevice

Get one device by id.

Parameters:

  • device_id

    (Required) –

    Target device ID to fetch.

Returns:

  • OqtopusDevice

    The requested device wrapped as an SDK device object.

get_job

get_job(job_id: str) -> OqtopusJobResult

Fetch one job by id and convert to typed SDK result.

Parameters:

  • job_id

    (Required) –

    Target job ID to fetch.

Returns:

get_job_result

get_job_result(job_id: str) -> OqtopusJobResult

Alias of :meth:get_job.

Parameters:

  • job_id

    (Required) –

    Target job ID to fetch.

Returns:

get_job_status

get_job_status(job_id: str) -> JobsGetJobStatusResponse

Get current status for one job.

Parameters:

  • job_id

    (Required) –

    Target job ID to get status for.

Returns:

  • JobsGetJobStatusResponse

    Raw job status response from the API.

get_sselog

get_sselog(job_id: str) -> JobsGetSselogResponse

Get encoded SSE log archive for one job.

Parameters:

  • job_id

    (Required) –

    Target SSE job ID.

Returns:

is_finished

is_finished(
    job_id: str,
    *,
    terminal_statuses: set[JobsJobStatus] | None = None,
) -> bool

Return whether the job is in terminal status.

Parameters:

  • job_id

    (Required) –

    Target job ID to inspect.

  • terminal_statuses

    (Optional, default: None ) –

    Statuses treated as terminal. Defaults to succeeded, failed, and cancelled.

Returns:

  • bool

    True when the job has reached a terminal status.

list_devices

list_devices() -> list[OqtopusDevice]

List available devices.

Returns:

  • list[OqtopusDevice]

    Available devices wrapped as SDK device objects.

list_jobs

list_jobs(
    *,
    fields: str | None = None,
    start_time: datetime | None = None,
    end_time: datetime | None = None,
    status: JobsJobStatus | None = None,
    q: str | None = None,
    page: int | None = None,
    size: int | None = None,
    order: str | None = None,
) -> list[JobsJob]

List jobs with optional filters.

Returns:

  • list[JobsJob]

    Jobs returned by the API.

refresh

refresh(job_id: str) -> OqtopusJobResult

Alias of :meth:get_job_result.

Parameters:

  • job_id

    (Required) –

    Target job ID to fetch.

Returns:

result

result(job_id: str) -> OqtopusJobResult

Alias of :meth:get_job_result.

Parameters:

  • job_id

    (Required) –

    Target job ID to fetch.

Returns:

run_estimation

run_estimation(
    job: OqtopusJobSpec,
    *,
    interval: float = 1.0,
    interval_backoff: float = 1.0,
    max_interval: float | None = None,
    timeout: float | None = 300.0,
    terminal_statuses: set[JobsJobStatus] | None = None,
    failure_statuses: set[JobsJobStatus] | None = None,
    on_status: Callable[[JobsGetJobStatusResponse], None]
    | None = None,
) -> OqtopusEstimationJobResult

Run an estimation job and return estimation-typed SDK result.

Parameters:

  • job

    (Required) –

    OqtopusJobSpec with job_type='estimation'.

  • interval

    (Optional, default: 1.0 ) –

    Polling interval in seconds.

  • interval_backoff

    (Optional, default: 1.0 ) –

    Backoff multiplier for polling interval.

  • max_interval

    (Optional, default: None ) –

    Upper bound of polling interval in seconds.

  • timeout

    (Optional, default: 300.0 ) –

    Timeout in seconds.

  • terminal_statuses

    (Optional, default: None ) –

    Statuses treated as terminal.

  • failure_statuses

    (Optional, default: None ) –

    Statuses treated as failures.

  • on_status

    (Optional, default: None ) –

    Callback invoked on each polled status.

Returns:

run_job

run_job(
    job: OqtopusJobSpec,
    *,
    interval: float = 1.0,
    interval_backoff: float = 1.0,
    max_interval: float | None = None,
    timeout: float | None = 300.0,
    terminal_statuses: set[JobsJobStatus] | None = None,
    failure_statuses: set[JobsJobStatus] | None = None,
    on_status: Callable[[JobsGetJobStatusResponse], None]
    | None = None,
) -> OqtopusJobResult

Submit one job spec, wait until completion, and return typed result.

Parameters:

  • job

    (Required) –

    OqtopusJobSpec.

  • interval

    (Optional, default: 1.0 ) –

    Polling interval in seconds.

  • interval_backoff

    (Optional, default: 1.0 ) –

    Backoff multiplier for polling interval.

  • max_interval

    (Optional, default: None ) –

    Upper bound of polling interval in seconds.

  • timeout

    (Optional, default: 300.0 ) –

    Timeout in seconds.

  • terminal_statuses

    (Optional, default: None ) –

    Statuses treated as terminal.

  • failure_statuses

    (Optional, default: None ) –

    Statuses treated as failures.

  • on_status

    (Optional, default: None ) –

    Callback invoked on each polled status.

Returns:

run_jobs_batch

run_jobs_batch(
    jobs: list[OqtopusJobSpec],
    *,
    submit_workers: int = 4,
    wait_workers: int = 4,
    interval: float = 1.0,
    interval_backoff: float = 1.0,
    max_interval: float | None = None,
    timeout: float | None = 300.0,
) -> list[OqtopusJobResult]

Submit multiple jobs, then wait for all of them.

Parameters:

  • jobs

    (Required) –

    List of OqtopusJobSpec.

  • submit_workers

    (Optional, default: 4 ) –

    Submission concurrency. Default is 4.

  • wait_workers

    (Optional, default: 4 ) –

    Waiting concurrency. Default is 4.

  • interval

    (Optional, default: 1.0 ) –

    Polling interval in seconds.

  • interval_backoff

    (Optional, default: 1.0 ) –

    Backoff multiplier for polling interval.

  • max_interval

    (Optional, default: None ) –

    Upper bound of polling interval in seconds.

  • timeout

    (Optional, default: 300.0 ) –

    Timeout in seconds.

Returns:

Raises:

  • TypeError

    If any item in jobs is not an OqtopusJobSpec.

  • ValueError

    If submit_workers is less than 1.

run_multi_manual

run_multi_manual(
    job: OqtopusJobSpec,
    *,
    interval: float = 1.0,
    interval_backoff: float = 1.0,
    max_interval: float | None = None,
    timeout: float | None = 300.0,
    terminal_statuses: set[JobsJobStatus] | None = None,
    failure_statuses: set[JobsJobStatus] | None = None,
    on_status: Callable[[JobsGetJobStatusResponse], None]
    | None = None,
) -> OqtopusMultiManualJobResult

Run a multi-manual job and return multi-manual-typed SDK result.

Parameters:

  • job

    (Required) –

    OqtopusJobSpec with job_type='multi_manual'.

  • interval

    (Optional, default: 1.0 ) –

    Polling interval in seconds.

  • interval_backoff

    (Optional, default: 1.0 ) –

    Backoff multiplier for polling interval.

  • max_interval

    (Optional, default: None ) –

    Upper bound of polling interval in seconds.

  • timeout

    (Optional, default: 300.0 ) –

    Timeout in seconds.

  • terminal_statuses

    (Optional, default: None ) –

    Statuses treated as terminal.

  • failure_statuses

    (Optional, default: None ) –

    Statuses treated as failures.

  • on_status

    (Optional, default: None ) –

    Callback invoked on each polled status.

Returns:

run_sampling

run_sampling(
    job: OqtopusJobSpec,
    *,
    interval: float = 1.0,
    interval_backoff: float = 1.0,
    max_interval: float | None = None,
    timeout: float | None = 300.0,
    terminal_statuses: set[JobsJobStatus] | None = None,
    failure_statuses: set[JobsJobStatus] | None = None,
    on_status: Callable[[JobsGetJobStatusResponse], None]
    | None = None,
) -> OqtopusSamplingJobResult

Run a sampling job and return sampling-typed SDK result.

Parameters:

  • job

    (Required) –

    OqtopusJobSpec with job_type='sampling'.

  • interval

    (Optional, default: 1.0 ) –

    Polling interval in seconds.

  • interval_backoff

    (Optional, default: 1.0 ) –

    Backoff multiplier for polling interval.

  • max_interval

    (Optional, default: None ) –

    Upper bound of polling interval in seconds.

  • timeout

    (Optional, default: 300.0 ) –

    Timeout in seconds.

  • terminal_statuses

    (Optional, default: None ) –

    Statuses treated as terminal.

  • failure_statuses

    (Optional, default: None ) –

    Statuses treated as failures.

  • on_status

    (Optional, default: None ) –

    Callback invoked on each polled status.

Returns:

run_sse

run_sse(
    job: OqtopusJobSpec,
    *,
    interval: float = 1.0,
    interval_backoff: float = 1.0,
    max_interval: float | None = None,
    timeout: float | None = 300.0,
    terminal_statuses: set[JobsJobStatus] | None = None,
    failure_statuses: set[JobsJobStatus] | None = None,
    on_status: Callable[[JobsGetJobStatusResponse], None]
    | None = None,
) -> OqtopusSseJobResult

Run an SSE job and return SSE-typed SDK result.

Parameters:

  • job

    (Required) –

    OqtopusJobSpec with job_type='sse'.

  • interval

    (Optional, default: 1.0 ) –

    Polling interval in seconds.

  • interval_backoff

    (Optional, default: 1.0 ) –

    Backoff multiplier for polling interval.

  • max_interval

    (Optional, default: None ) –

    Upper bound of polling interval in seconds.

  • timeout

    (Optional, default: 300.0 ) –

    Timeout in seconds.

  • terminal_statuses

    (Optional, default: None ) –

    Statuses treated as terminal.

  • failure_statuses

    (Optional, default: None ) –

    Statuses treated as failures.

  • on_status

    (Optional, default: None ) –

    Callback invoked on each polled status.

Returns:

run_sse_file

run_sse_file(
    *,
    file_path: str | Path,
    device_id: str,
    name: str | None = None,
    description: str | None = None,
    transpiler_info: dict[str, object] | None = None,
    simulator_info: dict[str, object] | None = None,
    mitigation_info: dict[str, object] | None = None,
    shots: int = 1,
    max_file_size: int = 10 * 1024 * 1024,
    interval: float = 1.0,
    interval_backoff: float = 1.0,
    max_interval: float | None = None,
    timeout: float | None = 300.0,
    terminal_statuses: set[JobsJobStatus] | None = None,
    failure_statuses: set[JobsJobStatus] | None = None,
    on_status: Callable[[JobsGetJobStatusResponse], None]
    | None = None,
) -> OqtopusSseJobResult

Build and run an SSE job directly from a script file and return SSE result.

Parameters:

  • file_path

    (Required) –

    Path to the Python script.

  • device_id

    (Required) –

    Target device ID.

  • name

    (Optional, default: None ) –

    Job name.

  • description

    (Optional, default: None ) –

    Job description.

  • transpiler_info

    (Optional, default: None ) –

    Transpiler settings.

  • simulator_info

    (Optional, default: None ) –

    Simulator settings.

  • mitigation_info

    (Optional, default: None ) –

    Error mitigation settings.

  • shots

    (Optional, default: 1 ) –

    Number of shots.

  • max_file_size

    (Optional, default: 10 * 1024 * 1024 ) –

    Max script size in bytes.

  • interval

    (Optional, default: 1.0 ) –

    Polling interval in seconds.

  • interval_backoff

    (Optional, default: 1.0 ) –

    Backoff multiplier for polling interval.

  • max_interval

    (Optional, default: None ) –

    Upper bound of polling interval in seconds.

  • timeout

    (Optional, default: 300.0 ) –

    Timeout in seconds.

  • terminal_statuses

    (Optional, default: None ) –

    Statuses treated as terminal.

  • failure_statuses

    (Optional, default: None ) –

    Statuses treated as failures.

  • on_status

    (Optional, default: None ) –

    Callback invoked on each polled status.

Returns:

status

status(job_id: str) -> JobsJobStatus

Get current job status enum for one job.

Parameters:

  • job_id

    (Required) –

    Target job ID to get status for.

Returns:

  • JobsJobStatus

    The current job status.

submit_job

submit_job(body: OqtopusJobSpec) -> JobsRegisterJobResponse

Submit one job and return submission response.

Parameters:

  • body

    (Required) –

    OqtopusJobSpec.

Returns:

  • JobsRegisterJobResponse

    Submission response for the created job.

Raises:

  • TypeError

    If body is not an OqtopusJobSpec.

submit_jobs

submit_jobs(
    jobs: Sequence[OqtopusJobSpec], *, max_workers: int = 4
) -> list[JobsRegisterJobResponse]

Submit multiple jobs in parallel.

Parameters:

  • jobs

    (Required) –

    List of OqtopusJobSpec.

  • max_workers

    (Optional, default: 4 ) –

    Submission concurrency. Default is 4.

Returns:

  • list[JobsRegisterJobResponse]

    Submission responses for all jobs.

Raises:

  • TypeError

    If any item in jobs is not an OqtopusJobSpec.

  • ValueError

    If max_workers is less than 1.

submit_jobs_async async

submit_jobs_async(
    jobs: Sequence[OqtopusJobSpec], *, max_workers: int = 4
) -> list[JobsRegisterJobResponse]

Submit multiple jobs concurrently in an async context.

Parameters:

  • jobs

    (Required) –

    List of OqtopusJobSpec.

  • max_workers

    (Optional, default: 4 ) –

    Submission concurrency. Default is 4.

Returns:

  • list[JobsRegisterJobResponse]

    Submission responses for all jobs.

Raises:

  • TypeError

    If any item in jobs is not an OqtopusJobSpec.

  • ValueError

    If max_workers is less than 1.

wait

wait(
    job_id: str,
    *,
    interval: float = 1.0,
    interval_backoff: float = 1.0,
    max_interval: float | None = None,
    timeout: float | None = 300.0,
    terminal_statuses: set[JobsJobStatus] | None = None,
    failure_statuses: set[JobsJobStatus] | None = None,
    on_status: Callable[[JobsGetJobStatusResponse], None]
    | None = None,
) -> OqtopusJobResult

Alias of :meth:wait_for_job.

Parameters:

  • job_id

    (Required) –

    Target job ID to wait for.

  • interval

    (Optional, default: 1.0 ) –

    Polling interval in seconds.

  • interval_backoff

    (Optional, default: 1.0 ) –

    Backoff multiplier for polling interval.

  • max_interval

    (Optional, default: None ) –

    Upper bound of polling interval in seconds.

  • timeout

    (Optional, default: 300.0 ) –

    Timeout in seconds.

  • terminal_statuses

    (Optional, default: None ) –

    Statuses treated as terminal.

  • failure_statuses

    (Optional, default: None ) –

    Statuses treated as failures.

  • on_status

    (Optional, default: None ) –

    Callback invoked on each polled status.

Returns:

wait_for_job

wait_for_job(
    job_id: str,
    *,
    interval: float = 1.0,
    interval_backoff: float = 1.0,
    max_interval: float | None = None,
    timeout: float | None = 300.0,
    terminal_statuses: set[JobsJobStatus] | None = None,
    failure_statuses: set[JobsJobStatus] | None = None,
    on_status: Callable[[JobsGetJobStatusResponse], None]
    | None = None,
) -> OqtopusJobResult

Poll one job until terminal status/timeout and return typed result.

Parameters:

  • job_id

    (Required) –

    Target job ID to wait for.

  • interval

    (Optional, default: 1.0 ) –

    Polling interval in seconds.

  • interval_backoff

    (Optional, default: 1.0 ) –

    Backoff multiplier for polling interval.

  • max_interval

    (Optional, default: None ) –

    Upper bound of polling interval in seconds.

  • timeout

    (Optional, default: 300.0 ) –

    Timeout in seconds.

  • terminal_statuses

    (Optional, default: None ) –

    Statuses treated as terminal.

  • failure_statuses

    (Optional, default: None ) –

    Statuses treated as failures.

  • on_status

    (Optional, default: None ) –

    Callback invoked on each polled status.

Returns:

wait_for_jobs

wait_for_jobs(
    job_ids: list[str],
    *,
    interval: float = 1.0,
    interval_backoff: float = 1.0,
    max_interval: float | None = None,
    timeout: float | None = 300.0,
    max_workers: int = 4,
) -> list[OqtopusJobResult]

Wait multiple jobs in parallel.

Parameters:

  • job_ids

    (Required) –

    List of job IDs to wait for.

  • interval

    (Optional, default: 1.0 ) –

    Polling interval in seconds.

  • interval_backoff

    (Optional, default: 1.0 ) –

    Backoff multiplier for polling interval.

  • max_interval

    (Optional, default: None ) –

    Upper bound of polling interval in seconds.

  • timeout

    (Optional, default: 300.0 ) –

    Timeout in seconds.

  • max_workers

    (Optional, default: 4 ) –

    Waiting concurrency. Default is 4.

Returns:

Raises:

  • ValueError

    If max_workers is less than 1.

wait_for_jobs_async async

wait_for_jobs_async(
    job_ids: list[str],
    *,
    interval: float = 1.0,
    interval_backoff: float = 1.0,
    max_interval: float | None = None,
    timeout: float | None = 300.0,
    max_workers: int = 4,
) -> list[OqtopusJobResult]

Wait multiple jobs concurrently in an async context.

Parameters:

  • job_ids

    (Required) –

    List of job IDs to wait for.

  • interval

    (Optional, default: 1.0 ) –

    Polling interval in seconds.

  • interval_backoff

    (Optional, default: 1.0 ) –

    Backoff multiplier for polling interval.

  • max_interval

    (Optional, default: None ) –

    Upper bound of polling interval in seconds.

  • timeout

    (Optional, default: 300.0 ) –

    Timeout in seconds.

  • max_workers

    (Optional, default: 4 ) –

    Waiting concurrency. Default is 4.

Returns:

Raises:

  • ValueError

    If max_workers is less than 1.