本文へスキップ
MZGrid

このページは英語版のみご利用いただけます。 英語版が正式な内容となります。

Jobs & account

Create, fund, monitor, read logs from and stop jobs, and read your account balances. Includes the Job object and status reference.

All endpoints on this page require Authorization: Bearer <token|key> with a session token or an API key. See Overview & authentication.

POST /v1/jobs

Create a job. Either pass an offerId, or a sku with autoSelect: true to let the scheduler choose the best offer.

FieldTypeRequiredDescription
offerIdstringone ofSpecific offer to run on.
sku + autoSelectstring, trueone ofLet the scheduler pick an eligible offer for this SKU.
templatestringyesTemplate id, e.g. llama-3.1-8b.
maxDurationHoursnumberyesMaximum run time. Determines the deposit.
config.modelstringnoHugging Face model id (vllm-openai).
config.imagestringnoContainer image (custom-docker, batch).
config.envobjectnoEnvironment variables for the container.
config.portsnumber[]noPorts to publish (custom-docker).
config.argsstring[]noExtra container arguments.
Shell
curl -X POST https://api.mzgrid.io/v1/jobs \
  -H "Authorization: Bearer $MZG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "rtx4090",
    "autoSelect": true,
    "template": "llama-3.1-8b",
    "maxDurationHours": 2,
    "config": { "env": { "HF_TOKEN": "hf_..." } }
  }'
JSON
{
  "job": {
    "id": "job_7f3a9c2d41",
    "jobIdBytes32": "0x6a0f…c93e",
    "status": "awaiting_funding",
    "template": "llama-3.1-8b",
    "sku": "rtx4090",
    "gpuName": "GeForce RTX 4090",
    "provider": "0x1d9a…07c3",
    "region": "us-west",
    "pricePerHour": "155.000000",
    "maxDurationHours": 2,
    "deposit": "310.000000",
    "createdAt": "2026-11-04T09:10:31Z",
    "txs": {}
  },
  "escrow": {
    "contract": "0x…",
    "jobIdBytes32": "0x6a0f…c93e",
    "provider": "0x1d9a…07c3",
    "pricePerHourWei": "155000000000000000000",
    "maxDurationS": 7200,
    "depositWei": "310000000000000000000",
    "specHash": "0x0b7e…5d12"
  }
}

Pass the escrow values unchanged to createJob or createJobWithPermit on the MZGridEscrow contract (escrow.contract). specHash commits to the template and configuration; the coordinator only dispatches the job if the on-chain JobFunded event matches. See MZGridEscrow.

Errors: 422 deposit_exceeds_cap if the deposit is above the chosen provider's cap, 422 insufficient_vram if the offer cannot run the template, 422 offer_unavailable if no GPU is free or no eligible offer exists for autoSelect.

POST /v1/jobs/:id/funded

Report the funding transaction. The coordinator verifies the JobFunded event on-chain, sets the job to funded and dispatches it to the provider.

HTTP
POST /v1/jobs/job_7f3a9c2d41/funded
Authorization: Bearer mzg_live_...
Content-Type: application/json

{ "txHash": "0x5c1e…9b07" }

Returns the updated Job. If the event is not found or does not match, the response is 409 conflict and the job stays awaiting_funding.

GET /v1/jobs

List your jobs, newest first. Optional status filter.

Shell
curl "https://api.mzgrid.io/v1/jobs?status=running" -H "Authorization: Bearer $MZG_API_KEY"
JSON
{
  "items": [
    {
      "id": "job_7f3a9c2d41",
      "jobIdBytes32": "0x6a0f…c93e",
      "status": "running",
      "template": "llama-3.1-8b",
      "sku": "rtx4090",
      "gpuName": "GeForce RTX 4090",
      "provider": "0x1d9a…07c3",
      "region": "us-west",
      "pricePerHour": "155.000000",
      "maxDurationHours": 2,
      "deposit": "310.000000",
      "endpointUrl": "http://198.51.100.23:41877",
      "createdAt": "2026-11-04T09:10:31Z",
      "startedAt": "2026-11-04T09:13:58Z",
      "txs": { "fund": "0x5c1e…9b07", "accept": "0xe4a2…7f10" }
    }
  ]
}

GET /v1/jobs/:id

Returns a single Job. A completed job:

JSON
{
  "id": "job_7f3a9c2d41",
  "jobIdBytes32": "0x6a0f…c93e",
  "status": "completed",
  "template": "llama-3.1-8b",
  "sku": "rtx4090",
  "gpuName": "GeForce RTX 4090",
  "provider": "0x1d9a…07c3",
  "region": "us-west",
  "pricePerHour": "155.000000",
  "maxDurationHours": 2,
  "deposit": "310.000000",
  "charged": "116.250000",
  "refund": "193.750000",
  "usedSeconds": 2700,
  "endpointUrl": "http://198.51.100.23:41877",
  "createdAt": "2026-11-04T09:10:31Z",
  "startedAt": "2026-11-04T09:13:58Z",
  "endedAt": "2026-11-04T09:58:58Z",
  "txs": { "fund": "0x5c1e…9b07", "accept": "0xe4a2…7f10", "settle": "0x93bd…22a6" }
}

Job object

FieldTypeDescription
idstringJob id used in API paths.
jobIdBytes32stringThe job's id in the escrow contract.
statusstringSee the status table below.
templatestringTemplate id.
sku, gpuNamestringGPU model.
providerstringProvider wallet address.
regionstringRegion code of the provider's machine.
pricePerHourstringMZG per GPU-hour, fixed at creation.
maxDurationHoursnumberMaximum run time.
depositstringpricePerHour × maxDurationHours, MZG.
chargedstring?MZG charged at settlement.
refundstring?MZG refunded at settlement.
usedSecondsnumber?Billed seconds.
endpointUrlstring?Base URL of the running service, once available.
createdAt, startedAt?, endedAt?stringLifecycle timestamps.
txs.fund?, txs.accept?, txs.settle?stringTransaction hashes on Base.

Status reference

StatusDescriptionTerminal
awaiting_fundingCreated; escrow not funded.no
fundedDeposit in escrow; waiting for the provider to accept (up to 10 minutes).no
startingAccepted on-chain; container being pulled and started.no
runningContainer running; usage being metered.no
completedSettled with completeJob; charged, refund and usedSeconds set.yes
failedSettled with failJob; full refund.yes
cancelledNot accepted within the accept window; cancelled by the client with cancelJob; full refund.yes
reclaimedNot settled by deadline + 1 h; client called reclaimTimeout; full refund.yes

GET /v1/jobs/:id/logs

Container log lines. Pass since (ISO timestamp) to fetch only newer lines.

JSON
{
  "lines": [
    { "t": "2026-11-04T09:14:20Z", "stream": "stdout", "text": "INFO: Loading model weights took 14.92 GB" },
    { "t": "2026-11-04T09:15:02Z", "stream": "stdout", "text": "INFO: Uvicorn running on http://0.0.0.0:8000" },
    { "t": "2026-11-04T09:15:40Z", "stream": "stderr", "text": "WARNING: Using max_model_len=8192" }
  ]
}

POST /v1/jobs/:id/stop

Stop a running job early. The coordinator settles with the seconds used so far and refunds the remainder. Returns the Job; status becomes completed once the settlement transaction is confirmed.

Shell
curl -X POST https://api.mzgrid.io/v1/jobs/job_7f3a9c2d41/stop -H "Authorization: Bearer $MZG_API_KEY"

GET /v1/account

JSON
{
  "address": "0x71C2…9aE4",
  "mzgBalance": "54777.190000",
  "escrowed": "3310.000000",
  "spent30d": "21275.100000",
  "jobsRunning": 2,
  "apiKeys": 3,
  "termsVersion": "2026-11-05",
  "termsAcceptedAt": "2026-11-05T09:10:05.000Z"
}
FieldDescription
mzgBalanceMZG in your wallet.
escrowedMZG currently deposited in escrow for open jobs.
spent30dMZG charged over the last 30 days.
jobsRunningJobs in funded, starting or running.
apiKeysNumber of active API keys.
termsVersionTerms of Service version this wallet last accepted (at sign-in or via /providers/terms), or null.
termsAcceptedAtWhen that acceptance was recorded, or null.