Skip to main content

Job Management

Use the SDK to monitor, rename, cancel, and delete jobs after submission.

List Jobs​

:func:atomiverse.list_jobs returns a :class:atomiverse.JobsPage with lightweight job summaries (no full result payloads) and a cursor for the next page:

import atomiverse

page = atomiverse.list_jobs(limit=50)

for job in page.jobs:
    print(job["job_id"], job.get("name"), job["state"])

# Get the next page
if page.has_more:
    page2 = atomiverse.list_jobs(limit=50, cursor=page.next_cursor)

Each job summary includes:

  • job_id — the server-assigned identifier
  • name — optional user-supplied name
  • state — pending, running, done, failed, or cancelled
  • job_type — e.g. single_point_energy, opt
  • created_at — timestamp of submission
  • billed_core_seconds — charge, if any
  • molecule_preview — formula and atom positions for rendering

Iterating over all jobs​

:func:atomiverse.iter_jobs handles pagination for you transparently:

# Yield every job in your history
for job in atomiverse.iter_jobs(limit=50):
    print(job["job_id"], job["state"])

# Limit to at most 200 jobs
for job in atomiverse.iter_jobs(limit=50, max_jobs=200):
    print(job["job_id"])

Rename a Job​

You can rename a submitted job using either the instance method or the module-level helper.

# Option 1: instance method
job.rename("benchmark-water-b3lyp")

# Option 2: module helper
atomiverse.rename_job(job.job_id, "benchmark-water-b3lyp")

Name rules are enforced server-side:

  • must not be empty after trimming
  • maximum 120 characters
  • printable characters only

If validation fails, the SDK raises atomiverse.AtomiverseError with HTTP 422.

Cancel a Job​

job.submit(wait=False)
job.cancel()
job.refresh()
print(job.state)  # CANCELLED (if cancellation was accepted)

Cancellation is best effort. If the job already finished, state remains terminal (DONE or FAILED).

Delete a Job​

Delete removes a job from your job history.

# Option 1: instance method
job.delete()

# Option 2: module helper
atomiverse.delete_job(job.job_id)

Deletion is allowed only for terminal jobs:

  • DONE
  • FAILED
  • CANCELLED

Attempting to delete PENDING or RUNNING jobs returns HTTP 409.

Visualize a Job​

You can open the job dashboard in the browser directly from the SDK with :meth:atomiverse.Job.visualize:

job.submit(wait=False)

# Open the job dashboard in a new browser tab
viewer_url = job.visualize()
print(viewer_url)
# https://atomiverse.com/job?job_id=...

visualize() opens the job dashboard for a submitted job in a new browser tab and returns the URL. If the browser cannot be opened (for example on a headless machine), the SDK prints the link and still returns the URL.

To control the behavior explicitly:

viewer_url = job.visualize(mode="browser")  # force new-tab behavior
viewer_url = job.visualize(mode="link")     # only return/print the link

open_browser= is still accepted as a temporary compatibility alias, but mode= is the preferred public API.

note

visualize() requires the job to have been submitted (a job_id must exist). Calling it before submit() raises a RuntimeError.

You can also get the dashboard URL without any browser interaction via the :meth:atomiverse.Job.job_dashboard_url property:

url = job.job_dashboard_url()
print(url)
# https://atomiverse.com/job?job_id=...

Production Notes​

For robust production usage:

  • Treat rename and delete as explicit user actions (do not run silently in background loops).
  • Handle 404 as idempotent for cleanup workflows where a job may already be removed.
  • Handle 409 on delete by reloading state and guiding users to cancel first.
  • Keep API keys out of source code (ATOMIVERSE_API_KEY env var is recommended).