Python SDK

インストール

標準ライブラリ以外の依存関係はなく、Python 3.9 以降が必要です。呼び出しはブロックし、いくつのスレッドから同時に呼び出してもかまいません。PyPI のパッケージ名は glac です。

pip install glac

クライアント

from glac import Glac, Sandbox

glac = Glac()                                       # GLAC_API_KEY and GLAC_API_URL; or Glac(api_key=..., base_url=...)

app = glac.cube.deploy("ghcr.io/acme/api:1.4", name="api", port=8080)   # Cube: waits until it serves
print(app.url)

sbx = glac.sandboxes.create(image="python:3.12")    # Sandbox
print(sbx.run("python3 -c 'print(6*7)'").stdout)

drive = glac.drives.create(name="data", size_bytes=10 << 30)               # Drive: disks that outlive sandboxes

print(Sandbox.run("echo hello").stdout)             # the shorthand: a sandbox for one command, on the default client

glac.cube.deploy は glac deploy と同じです。api という名前のアプリ（なければ先に作成）に新しいバージョンを作り、それがアプリのトラフィックを受け取るまで待ちます。最後の行は唯一の短縮形で、サンドボックスの SDK にある、クライアントなしの 1 行の書き方です。with glac.sandboxes.create() as sbx: はブロックの終わりでサンドボックスを削除します。それ以外に何かを削除するのは、使い捨てのサンドボックスと、自分で呼ぶ delete() だけです。

Glac() は、キーを GLAC_API_KEY から、アドレスを GLAC_API_URL（デフォルトは https://api.glac.ai）から読みます。

製品は名前空間で、それぞれ、たどってきたクライアントを持っています。オブジェクトには API の名前を使います。キューブは App（API ではアプリ）で、ほかに Sandbox、Snapshot、Drive、DriveSnapshot（ドライブのスナップショット）、Volume、Backup（ボリュームのバックアップ）、Domain、SshKey、Secret、Variable、Version、Instance、Deploy があります。それらに対して行う操作は、それぞれのメソッドです：sbx.run、app.deploy、drive.delete。

短縮形。Sandbox.run、Sandbox.create、Sandbox.get、Sandbox.get_or_create、Sandbox.list は、初めて必要になったときに環境変数から作られ、以降共有されるクライアントでの glac.sandboxes の呼び出しです。client= で別のクライアントを指定できます。コードは同じです。それ以外に、クライアントなしで使えるものはありません。

一部のオプションでは None に意味があります（sleep_after_seconds=None はスリープしない、env={"KEY": None} はそのキーを削除する）。そのため、指定しないオプションは UNSET（from glac import UNSET）で、元のまま残ります。

キューブ

キューブ（API ではアプリ）は、固有のアドレスでサービスとして動くイメージで、インスタンスはリクエストに必要なだけ動き、リクエストがなければ 1 つもありません。デプロイはすべてバージョンになり、準備ができた時点でトラフィックを受け取ります。アプリはコントロールプレーンの機能で、単独で動くノードに対しては、どの呼び出しもノードの 404 no_such_route になります。

from glac import DeployError, Glac

glac = Glac()
app = glac.cube.deploy("public.ecr.aws/docker/library/python:3.12-alpine", name="hello",
                          start_command=["python3", "-m", "http.server", "8000"], port=8000)   # waits for version 1
print(app.url)
app.deploy(env={"STAGE": "prod"})               # a new version; waits until it has the traffic
try:
    app.deploy(start_command="exit 3")
except DeployError as e:                        # the traffic stays where it was
    print(e.code, e.version.number)
app.rollback(1)
for line in app.logs(follow=False):
    print(line)

バージョンをビルドする呼び出しは、wait=False を指定しない限りそれを待ち、失敗すると、バージョン自身のコードと出力を持つ DeployError を送出します。timeout_seconds= を指定すると、その時間が過ぎた時点で GlacTimeoutError を送出し、デプロイはそのまま続きます。

glac.deploys で、プロジェクトの複数のサービスをまとめてデプロイします（プロジェクトのデプロイ）。コントロールプレーンは、それぞれが待つものの順に進め（ステートフルなサービス、ジョブ、残りの順で、残りはまとめて切り替え）、失敗したデプロイは、まだ切り替わっていないものを何も切り替えません。

d = glac.deploys.create({"api": {"image": "ghcr.io/acme/api:2"}, "web": {}})   # waits until it is over
print(d.status, [(s.service, s.status, s.version) for s in d.services])

create(services, wait=True, timeout_seconds=None) は、各サービスのバージョンのフィールドを API と同じ形で受け取り（{} ならそのまま）、待ちます（Deploy.wait）。置き換わったデプロイがあればそれを追います。失敗すると、deploy、service、デプロイの code（job_failed、job_timed_out、job_lost など）を持つ DeployError を送出します。get(id) と list()（新しい順）で読み取ります。Deploy は status、cause、services（DeployService）、error、replaced_by、steps と、各時刻を持ちます。

サンドボックス

glac.sandboxes.run（とクラスの Sandbox.run）は 1 つのコマンドのためのサンドボックスで、sbx.run はサンドボックス sbx でコマンドを実行します。出力を逐次受け取るには次のようにします。

res = sbx.run("make", on_stdout=lambda text: print(text, end=""))   # watch and wait

cmd = sbx.exec("node server.js")                                    # do not wait
for piece in cmd.output():                                          # piece.stream, .text, .data, .offset
    print(piece.text, end="")

出力は、コマンドが書いたとおりのバイトで届きます。res.stdout は str（UTF-8。デコードできないバイトは置き換え）、res.stdout_raw は bytes です。

ドライブ

ドライブは、サンドボックスより長く残るプロジェクトのディスクです。サンドボックスの作成時か実行中に、一度に 1 つのサンドボックスが読み書き可能でマウントし、サンドボックスがなくなると中身ごと保持され、次のサンドボックスがマウントできます。次のサンドボックスは同じリージョンのもの、またはマシンがホームのオブジェクトストアを読める別のリージョンのもの（後述）です。書き込まれるそばからリージョンのオブジェクトストアにコピーされるため、別のノード上のサンドボックスもマウントできます。その場合は先にそこへ運ばれます。課金されるのは書き込まれたものだけです（used_bytes）。スナップショットはオブジェクトストア内のドライブのバージョンで、いくつものサンドボックスが同時に読み取り専用でマウントでき、そこから新しいドライブをフォークしたり、ドライブをその状態に復元したりできます（後述）。ドライブはコントロールプレーンの機能で（/v1/drives）、単独で動くノードに対しては、どの呼び出しもノードの 404 no_such_route になり、そのノードのディスクはボリュームです（後述）。

from glac import DriveMount

drive = glac.drives.create(name="data", size_bytes=10 << 30)
sbx = glac.sandboxes.create(drives=[DriveMount("/data", drive)])
sbx.run("echo kept > /data/note")
glac.drives.detach(sbx, drive)
other = glac.sandboxes.create()
glac.drives.attach(other, drive, "/data")
print(other.run("cat /data/note").stdout)      # kept

• ドライブは一度に 1 つのサンドボックスのものです。ほかのサンドボックスが持っているドライブは拒否され（409 drive_attached）、アタッチ中のドライブの削除も拒否されます。キー別インスタンスのドライブは、キーとともに削除されます（409 key_drive）。
• データベースのドライブ（drive.managed_by、{"object": "database", "id": "db-…"}）を読み書き可能でマウントできるのはデータベースのインスタンスだけで、名前の変更、復元、削除はデータベースを通じて行います。ここでのそれらの呼び出しと、読み書き可能なマウントは拒否されます（409 managed_by_database）。そのスナップショットとフォークはプロジェクトで取得でき、スナップショットは誰でも読み取り専用でマウントできます。
• 別のノードが保持しているドライブは、先にサンドボックスのノードへ運ばれます。オブジェクトストアがまだ現在の状態を保持していない間（503 copy_behind）や、運べなかった場合（503 drive_not_brought）、呼び出しは retryable です。クライアントは retries の指定どおりに再試行し、それでも失敗すれば例外を送出するので、少し後に再度要求してください。
• リージョンをまたぐ場合（slice D9）。ドライブのホーム（home）とは、そのコピーを保持するオブジェクトストアのリージョンで、作成されたリージョンです。別のリージョンのサンドボックスも、そのリージョンのマシンがホームのストアを読める場合はマウントできます（読めなければ 409 not_on_one_machine）。ドライブはバージョンとして手放され、そこで引き継がれ、ゲストが読むのに合わせてホームのストアから読み取られ、ゲストが書き込むものは今いるリージョンのストアに送られます（region）。ホームは、そこに 1 時間いると追従します。glac.drives.move_home(drive)（drive.move_home()）を使えばすぐに移ります。マシンがホームのストアに残っているものを自分のストアにコピーし、何も残らなくなった時点で home が新しいリージョンになります。drive.home_move が移動の進み具合を示します（asked_at、asked_by、copied_objects、copied_bytes、objects_left、error）。古いホームのコピーは、保持しているどのバージョンも必要としなくなった時点で消えます（1 日後）。ドライブのホームが移るのは最大で 6 時間に 1 回で（409 home_moved_recently）、ホームが現在のリージョンにあるドライブでは 409 home_here になります。
• プランの制限：無料プランでは最大 10 GiB のドライブを 3 つ（合計 15 GiB）、有料プランでは最大 1 TiB のドライブを 500 個です（403 drive_limit_reached）。
• glac.usage(drive=...)、kind="drive"、group_by="drive" は、ドライブが保持した量、書き込まれた量、キャッシュ外から読まれた量を報告します。イベント drive.created、drive.deleted、drive.attached、drive.detached は EventDrive か EventDriveAttached を、drive.snapshot.created と drive.snapshot.deleted は EventDriveSnapshot を運びます。
• glac.drives.attach の mode は read_write です。スナップショットの読み取り専用のマウントは attach_snapshot で行い、これはスナップショットを返します（スナップショットなしの mode="snapshot" は 400 missing_field）。

**ドライブのスナップショット。**スナップショットはオブジェクトストア内のドライブのバージョンで、そのためにも、フォーク、復元、読み取り専用のマウントのためにも、何もコピーされません。

snap = drive.snapshot(name="before-upgrade")             # a running sandbox has the Drive: its writes held a moment, "paused"
reader = glac.sandboxes.create(drives=[DriveMount("/before", drive, snapshot=snap)])   # read-only, any number of sandboxes
copy = glac.drives.fork(drive, name="data-copy", from_snapshot=snap)
glac.drives.detach(sbx, drive)
glac.drives.restore(drive, snap)                         # once no sandbox has it read-write

• 実行中のサンドボックスが持っているドライブは、書き込みを短時間（最大 10 秒。超えると再試行可能な 503 unavailable）止めてスナップショットを取ります。fs_consistent=True なら先にファイルシステムを凍結し（consistency は frozen。サンドボックスのエージェントが凍結できなければ 409 not_frozen）、そうでなければ、停電時と同じようにマシンを一時停止します（paused）。実行中のサンドボックスが持っていないドライブは、そのまま取ります（at_rest）。
• スナップショットはドライブより長く残り、ドライブはスナップショットを残して削除されます。ドライブの削除後も、スナップショット自体が削除されるまで（snap.delete()）、ドライブの ID で一覧表示、読み取り、フォーク、マウントができます。単独で保持する量（exclusive_bytes）に対して、1 時間ごとに、ドライブのデータの料金（1 GB-月あたり $0.02）で課金され、glac.usage(snapshot=snap.id) がそれを報告します。
• フォークはすぐにマウントできる新しいドライブで、サイズは元のドライブと同じで、作成元を示します（parent_drive_id、root_drive_id）。プランのドライブ数に数えられ（403 drive_limit_reached）、プロジェクトにすでにある名前は 409 name_taken になります。ほかのドライブと同じく、used_bytes、つまり内容全体で課金されます。10 GB のスナップショットのフォークは、10 GB のドライブとして課金されます。
• 復元は、ドライブの最新のバージョンの後に、スナップショットの内容を持つ新しいバージョンを書き込みます。その間のバージョンは、スナップショットかフォークが保持している限り残るため、古いスナップショットに復元した後に新しいスナップショットに復元することもできます。サンドボックスがドライブを読み書き可能で持っている間は拒否されます（409 drive_attached。先にデタッチしてください）。
• 読み取り専用のマウント：ドライブのリージョンのどのノード上でも、ドライブを誰が持っていても、ドライブが削除された後でも、いくつものサンドボックスが同時にマウントでき、ゲストは書き込めません。ブロックはゲストが読むのに合わせてオブジェクトストアから届きます。このキャッシュ外の読み取りに料金はかからず、使用量ではそのサンドボックスの下に表示されます（glac.usage(sandbox=...)、drive_cold_read_bytes）。そのサンドボックスのマシンがすでに保持しているものの読み取りにも料金はかかりません。読み取り専用のマウントを持つサンドボックスは、別のマシンへ移動しません。
• ドライブのノードがオブジェクトストアに何もコピーしない場合、スナップショット、フォーク、復元はありません（409 not_copied）。アプリのバージョンはドライブを読み書き可能でしかマウントせず（そこでの mode snapshot は 400 invalid_field）、スナップショットの読み取り専用のマウントはサンドボックス用です。

glac.volumes は API の /v1/volumes で、ドライブの下にあるディスクです。移行のために残されています。これにしかないのは、ディスクがボリュームである単独で動くノードと、複数のサンドボックスが同時にマウントするファイルシステムである共有ボリュームです。コントロールプレーンは、プロジェクトのキーに対して通常のボリュームを作りません。

from glac import VolumeMount

vol = glac.volumes.create(name="team", shared=True)     # no size: a large limit, and the space of what is written
sbx = glac.sandboxes.create(volumes=[VolumeMount("/team", vol)])
print([v.name for v in glac.volumes.list()], glac.volumes.get("team").id)

マウント中のボリュームは削除されません（409 conflict）。sbx.update(volumes=[]) で外してください。

**ボリュームのバックアップ。**バックアップは、ある瞬間のボリューム（ドライブもボリュームです）のコピーで、オブジェクトストアに、期限が来るまで保持されます。呼び出しによって、ボリュームのルールに従って毎日、またはサービスの新しいバージョンがインスタンスを置き換える前に取得されます。ドライブのスナップショットと違い、それ自体が独立したコピーで、それだけからボリュームを作ることができ、元のボリュームより長く残ります。ボリュームのバックアップは前回以降に変わったものだけを保持し、複数のバックアップが必要とするブロックは、そのうち最も古いもので 1 回だけ課金されます。ストアがすべてを受け取るまでは making、その後は ready で、それ以降はストアが保持する量（stored_bytes）に応じて、スリープ中のサンドボックスが保持するものと同じ料金で課金されます（バックアップ）。バックアップはコントロールプレーンの機能です。

import time

b = glac.volumes.backup("data", expires_in_days=7)      # "making", then "ready"
while b.refresh().status == "making":
    time.sleep(1)
copy = glac.backups.restore(b, name="data-back")        # a new volume: "restoring", then "ready"

• バックアップから作るボリュームは、バックアップ元のボリュームと同じサイズと種類で（from_backup では size_bytes と shared を指定しません：ValueError）、バックアップのリージョンに作られます。status は、バックアップ全体を保持するまでは restoring、その後は ready で、それまではアタッチできません。from_backup がバックアップを示します。配置先のマシンで復元できない場合、コントロールプレーンはリージョンの別のマシンにもう一度作ります。そのとき vol.info["restore_attempt"] は 2 になり、vol.info["first_failure"] が最初の試行に失敗した理由を示します。それも失敗すると failed（vol.info["failure"]）になり、削除しかできません。
• glac.usage(backup=...)、kind="backup"、group_by="backup" は、バックアップが保持した量を、状態の計測項目（state_gb_hours）で報告します。glac.billing()["meters"]["state"]["backups_gb_hours"] は、その計測項目のうちバックアップの分を示します。

ドメイン

プロジェクトのドメインは、デフォルトのアドレスと同じくアプリへ、またはサンドボックスのポートへ向かう独自の名前です（独自ドメイン）。ドメインはコントロールプレーンの機能です。

domain = glac.domains.create("api.example.com", app="api")
print(domain.verification["records"])

ブラウザ

**未公開。**Glac のブラウザはまだ利用できません。以下は公開に先立つ、現時点での SDK です。

セッションは Glac がホストする Chromium で、Playwright、Puppeteer など任意の Chrome DevTools Protocol（CDP）クライアントから外部で操作します。クライアントの接続中は稼働し、最後のクライアントが離れて sleep_after_seconds が過ぎると、ページを保持したままスリープします。CDP クライアントに必要なのは cdp_url だけです。認証情報はアドレスのホスト名に含まれるため、repr には表示されません。

with glac.browsers.create(name="agent-42") as session:   # deleted when the block ends
    browser = session.connect()
    page = browser.contexts[0].pages[0]
    page.goto("https://example.com")
    page.screenshot(path="shot.png")

セッションは、ほかのインスタンスと同じく、使用したキューブのリソースで課金されます。処理している間の CPU、稼働中のメモリ、送信トラフィックです（料金とプラン）。session.awake_seconds は稼働していた時間です。

プロファイルとは、訪れたサイトに対してブラウザが誰であるかを示すものです。Cookie、Local Storage、IndexedDB、Session Storage、設定で、キャッシュは含みません。プラットフォームがプロジェクトのために保持し、単独では課金されず、セッションがそのキーを持つことはありません。一度ログインして保存すれば、そのプロファイルで作成したセッションはすべてログイン済みになります。

session = glac.browsers.create(profile={"name": "acme-login", "save": True})   # saved again when it is deleted
browser = session.connect()
# ... log in ...
session.save_profile()                       # the browser restarts, and a connected client reconnects
later = glac.browsers.create(profile="acme-login")   # logged in

保存では、ブラウザは保持しているものを書き出せるように、閉じるときと同じ手順で停止され、再び起動されます。読み込みでは、セッションを返す前に、セッションのブラウザがプロファイルを使って起動されます（1 MB のプロファイルで数百ミリ秒）。1 つのプロファイルの保存は一度に 1 つで、保存の途中のほかの保存は 409 profile_busy で拒否されます。削除したプロファイルはすぐに消え、アーカイブは 30 日後に削除されます。

有料プランでは、セッションの Web トラフィックを、CONNECT を受け付ける自前の HTTP プロキシ経由で送信できます（無料プランでは 403 proxy_not_on_plan）。ポート 80 と 443 への接続は、ブラウザの隣にあるリレーによってプロキシを経由し、ブラウザには何も知らされません。そこでは QUIC は拒否されるため、ブラウザは TCP 上の HTTP で通信します。認証情報はプラットフォームが保持し、どのレスポンスにも含まれません（session.proxy に表示されるのはアドレスとユーザー名です）。

session = glac.browsers.create(name="agent-42", proxy="http://user:password@proxy.example.com:3128")
session.update(proxy="http://other:password@proxy.example.com:3128")   # the browser goes on; its next connections go through this one
session.update(proxy=None)                                             # none
print(session.refresh().proxy_bytes)                                   # what went through it, both ways

proxy は {"url": ...} も受け付けます。プロキシがトンネルを受け付けないページには、HTTP なら 502 proxy_failed が返ります（HTTPS ならハンドシェイクに失敗します）。プロキシを通過したものは、ほかと同じくセッションのトラフィックです。自前のプロキシを参照してください。

セッションの ID はサンドボックスの ID です。glac.sandboxes.get(session.id) で、中でコマンドを実行できます。Playwright の非同期 API では、await p.chromium.connect_over_cdp(session.cdp_url) が connect と同じことをします。セッションはコントロールプレーンの機能です。

データベース

データベースはマネージド Postgres です。ドライブ上で動く専用の PostgreSQL で、何も要求がないときはスリープし、接続があればセッションを保ったまま復帰します。約 2 秒で作成され、ルートブランチ main と、オーナー glacdb_owner（glac_superuser のメンバーで、スーパーユーザーではない）を持ちます。オーナーのパスワードは create と reset_password のレスポンスにしか含まれず、どこにも保存されません。そのどちらかが返したデータベースの connection_string() には、パスワードが含まれます。

import psycopg

db = glac.databases.create("shop")                     # ready, with the owner's password
with psycopg.connect(db.connection_string()) as conn:  # from a sandbox or a service of the project
    conn.execute("create table orders (id bigserial primary key, total numeric)")

データベースには、プロジェクトのネットワーク上で、そのサンドボックス（project_network で作成）とサービスから名前でアクセスします。これが private_uri です。エッジが PostgreSQL を提供する場合は、パブリックアドレスでどこからでもアクセスできます（connection_uri、ポート 5432、TLS のみ。プーラーは pooled_uri）。提供するエッジがない場合や、データベースに名前を付けるリージョンがない場合は None で、接続文字列は、それらがあればそれらを使います。repr も、ここにあるほかのどれも、パスワードを表示しません。データベースのアプリとドライブは managed_by とともに一覧表示され、glac.databases を通じてのみ変更されます。データベースはコントロールプレーンの機能です。

マネージドアプリケーション

カタログのアプリケーション（たとえば Rivet）は、プロジェクトに専用のキューブのリソースとしてインストールされます。アプリ、ボリューム、シークレット、バケットで、インストールのラベルが付き、変更はインストールを通じてのみ行い、それぞれのリソースとして課金されます（マネージドアプリケーション）。インストールのレスポンスには、秘密のもの（管理者トークン、それを含むエンドポイント）も含め、すべての出力値があり、読み取りでそれらが表示されるのは admin スコープを持つキーだけです。インストールのオブジェクトは、以前のレスポンスが返し、後のレスポンスが隠した出力値をそれぞれ保持します。

rivet = glac.catalogue.get("rivet")                  # its parameters, and a month of it in Cube's meters
print(rivet.calculator["month"])
engine = glac.installations.create("rivet", parameters={"disk_gib": 20})   # waits until it is ready
print(engine.outputs["endpoint"])                    # RIVET_ENDPOINT, its token in it

マネージドアプリケーションはコントロールプレーンの機能です。

シークレットと変数

glac.secrets.put("GHCR", "me:ghp_…", allowed_hosts=["ghcr.io"])     # never given back; goes to these hosts only
glac.secrets.update("GHCR", allowed_hosts=["ghcr.io", "*.example.com"])
glac.variables.put("REGION", "eu")                                 # an app's env refers to it: "${{ shared.REGION }}"
print([s.name for s in glac.secrets.list()], {v.name: v.value for v in glac.variables.list()})
glac.secrets.delete("GHCR")

シークレットは名前だけで識別されるため、各呼び出しは名前か、一覧で得た Secret を受け付け、値を含むレスポンスはありません。共有変数はコントロールプレーンの機能です。

プロジェクト、アカウント、請求

Webhook、API キー、利用上限額、プロジェクト。glac.webhooks は、プロジェクトのイベントを自前のアドレスに送ります：create(url, events=, enabled=)（各配信に署名する secret は、このレスポンスにだけ含まれます）、get、list、update、delete。glac.keys はプロジェクトの API キーです：create(name=, scopes=, expires_at=)（キーそのもの key は、このレスポンスにだけ含まれます）、get、list、delete。glac.limits() と glac.update_limits(usd) は、プロジェクトの利用上限額と今月の支出額で（None で上限を外します）、sbx.limits() と sbx.update_limits(usd) はサンドボックス自体のものです。glac.request_limit(limit, wanted, why) は、アカウントの申請による上限の引き上げを 1 つ申請します（名前で指定する上限、"volumes"、"volume_bytes"。バイト数の 2 つはバイト単位。同じ上限の申請が待機中なら 409 limit_request_pending）。glac.limit_requests(limit=, cursor=) と glac.limit_request(id) は、申請をオペレーターの回答とともに読み取ります（LimitRequest：status は pending、granted、refused。granted、answer）。glac.update_project(delete_after_idle_days=30) は、スリープが何日続いたらサンドボックスを削除するかを設定します（None なら削除しない）。コントロールプレーンの機能です。Webhook と API キー、プロジェクトの上限の設定、update_project には admin スコープを持つキーが必要で、サンドボックスの上限の設定には write が必要です。

ログのエクスポート先、監査ログ、請求関連の書類。glac.destinations は、プロジェクトのアプリのログ（とメトリクス、リクエストのトレース：signals=["logs", "traces"]）のエクスポート先（OpenTelemetry のエンドポイント）です：create(name, endpoint=, headers=, ...)（作成時にすぐ 1 件のレコードで試す：status["connected"]）、get、list、update、delete、test（すぐに 1 件送る）。ヘッダーの値は認証情報で、エクスポート先の作成時か変更時に送られ、どのレスポンスにも含まれません（返されるのはヘッダーの名前だけです）。glac.audit(limit=, cursor=) は、プロジェクトの監査ログの 1 ページ分を新しい順に返します（実行者、メソッド、パス、ステータス）。読み取り以外のすべての呼び出し（拒否されたものも含む）と、オペレーターによるアプリのログの読み取りすべてです。glac.statement("2026-09") は 1 か月の明細（指定しなければ今月。その月の date も可）で、データベースごとの行（databases：その月の使用量、履歴と階層化データを別記したもの、それを定価で換算した額）を含みます。glac.invoices() は Stripe にある請求書（PDF のリンク付き）、glac.notices() はアカウントに送られたメール、glac.withdrawals() は今撤回できる購入と行った撤回（EEA または英国の消費者は、購入から 14 日以内であれば撤回できます）、glac.withdraw(charge_id, name=, email=) は購入者自身による撤回の意思表示で、すぐに受理されます。コントロールプレーンの機能です。エクスポート先の作成、変更、テスト、削除、監査ログの読み取り、撤回には admin スコープを持つキーが、それ以外には読み取りのできるキーが必要です。

どれも API のレスポンスを dict で返し、TypedDict（Account、Billing、Balance、Charge、Project、Event、EventAutoReloadNoRequest、EventInstanceRestarted、EventInstanceUpgraded、EventInstanceReverted、EventInstanceUpgradeFailed、EventLimitRequest など）がその中身を示します。請求、残高、プロジェクトはコントロールプレーンの機能で、単独で動くノードは 404 no_such_route を返します。

**イベントのデータ。**コントロールプレーンのイベントの種類ごとに、その data（event["data"]）の TypedDict があり、説明のスキーマにちなんだ名前が付いています。データベースのもの：EventDatabase（database.created：region と PostgreSQL の version 付き。database.deleted：7 日間保持されるドライブのスナップショット final_snapshot_id 付き）、EventDatabaseBranch（database.branch_created：parent 付き。database.branch_deleted：reason 付き）、EventDatabaseRestored（database.restored：時点 at と、復元前の状態を保持するブランチ old_branch_id）、EventDatabaseArchive（database.archive_failing：since、連続して失敗したセグメントの数 failures、その間に復元で遡れる範囲 archived_until、オブジェクトストアの error。database.archive_recovered：recovered_at）、EventDatabaseGap。ほかも同様です。サンドボックスのもの（EventSandboxSlept、EventSandboxWoke、EventSandboxMoved、EventSandboxDeleted など）、アプリとそのキーのもの（EventApp、EventAppFailed、EventKeyCreated など）、プロジェクトのデプロイとキー、バックアップ、ドメイン、エクスポート先、ドライブのスナップショットのもの（EventProjectDeployed、EventBackup、EventDomain、EventDestination、EventDriveSnapshot など）、そしてアカウントのプラン、チャージ、返金、撤回、残高、クレジット、ストレージ、送信量の上限、利用上限額、保留、未払いのもの（EventSubscriptionPeriod、EventTopupCollected、EventWithdrawalReceived、EventBalance、EventInDebt など）です。その種類のすべてのイベントにあるわけではないキーは、型では省略可能になっています。

**すぐに受け取る購入（start_now）。**欧州経済領域または英国の消費者（確認済み、または確認中の税番号を持たないアカウント）は、購入から 14 日以内であれば撤回でき、購入したものがすぐに提供されるのは、本人が明示的に求めた場合だけです。top_up(20, start_now=True)、update_billing(plan="paid", start_now=True)（無料プランから購入する有料プラン）、update_balance(auto_reload=True, start_now=True)（自動チャージがオンの間のすべての自動チャージ）が、その要求を、コンソールのチェックボックスの横に表示される文言（GET /v1/billing/withdrawals の right.start_now にもあるもの）で伝えます。

撤回できる 14 日間のうちに、この購入をすぐに提供するよう求めます。撤回した場合は、それまでに提供された分を支払います。チャージのクレジットをすべて使った時点で全額が提供されたことになり、それ以降は撤回できなくなることを理解しています。

サービスはすぐに始まります。14 日以内なら購入者はまだ撤回でき、その場合はそれまでに提供された分を支払います。すべてが提供されると（チャージのクレジットをすべて使うと）、撤回する権利はなくなります。この要求は、購入する本人が求めたときだけ指定してください。SDK は、指定されない限り決して送りません。指定がなければ、そのようなアカウントは、国名を挙げ、要求の文言を引用したメッセージとともに 400 start_now_required（param は start_now）で拒否され、何も購入されません。要求なしで自動チャージをオンにしたアカウントでは何もチャージされず、月に 1 回通知されます（イベント auto_reload.no_request）。

エラー

0 以外の終了コードは結果です。res.exit_code を読んでください。API のエラーは、どの製品の呼び出しであっても、status、type、code、param、retryable、request_id、message、そしてエラーのページの該当するコードを指す docs_url を持つ GlacError を送出します。接続できない場合は GlacConnectionError、タイムアウトは GlacTimeoutError（TimeoutError でもあります）です。立ち上がらなかったバージョンや失敗したプロジェクトのデプロイは DeployError、断念したログの読み取りは LogsError で、どちらも GlacError です。お金に関するエラー（402 account_in_debt、403 trust_limit_exceeded、409 no_card、400 start_now_required など）は、コントロールプレーン自身のメッセージを持ち、解除する方法を示します。

知っておくべき動作

• **スリープ中のサンドボックス。**サンドボックスがスリープ中や起動中であることを理由に失敗する呼び出しはありません。待ってから続行します。復帰させるための呼び出しはありません。run() と wait() は待っている呼び出しとして数えられるため、その間サンドボックスは稼働し続けます。cmd.output() の読み取りは数えられません。
• **再試行。**応答のない呼び出しや retryable のエラーは、0.2 秒から倍々に間隔を空けて 2 回再試行されます（retries=）。すべての POST には Idempotency-Key が付くため、再試行でサンドボックスが 2 つ作られたり、コマンドが 2 回実行されたりすることはありません。
• タイムアウト。Glac(timeout_seconds=)（指定しなければ 900 秒）は、コマンド自体の時間に加えて API を待つ時間です。run(timeout_seconds=) はコマンドの制限時間で、過ぎるとコマンドは強制終了され、結果は timed_out になります。
• スレッド。Glac、Sandbox、Command は、複数のスレッドから使えます。asyncio の API はまだないため、await asyncio.to_thread(sbx.run, "make") を使ってください。