此页面仅提供英文版本。 以英文版本为准。
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.
| Field | Type | Required | Description |
|---|---|---|---|
offerId | string | one of | Specific offer to run on. |
sku + autoSelect | string, true | one of | Let the scheduler pick an eligible offer for this SKU. |
template | string | yes | Template id, e.g. llama-3.1-8b. |
maxDurationHours | number | yes | Maximum run time. Determines the deposit. |
config.model | string | no | Hugging Face model id (vllm-openai). |
config.image | string | no | Container image (custom-docker, batch). |
config.env | object | no | Environment variables for the container. |
config.ports | number[] | no | Ports to publish (custom-docker). |
config.args | string[] | no | Extra container arguments. |
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_..." } }
}'{
"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.
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.
curl "https://api.mzgrid.io/v1/jobs?status=running" -H "Authorization: Bearer $MZG_API_KEY"{
"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:
{
"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
| Field | Type | Description |
|---|---|---|
id | string | Job id used in API paths. |
jobIdBytes32 | string | The job's id in the escrow contract. |
status | string | See the status table below. |
template | string | Template id. |
sku, gpuName | string | GPU model. |
provider | string | Provider wallet address. |
region | string | Region code of the provider's machine. |
pricePerHour | string | MZG per GPU-hour, fixed at creation. |
maxDurationHours | number | Maximum run time. |
deposit | string | pricePerHour × maxDurationHours, MZG. |
charged | string? | MZG charged at settlement. |
refund | string? | MZG refunded at settlement. |
usedSeconds | number? | Billed seconds. |
endpointUrl | string? | Base URL of the running service, once available. |
createdAt, startedAt?, endedAt? | string | Lifecycle timestamps. |
txs.fund?, txs.accept?, txs.settle? | string | Transaction hashes on Base. |
Status reference
| Status | Description | Terminal |
|---|---|---|
awaiting_funding | Created; escrow not funded. | no |
funded | Deposit in escrow; waiting for the provider to accept (up to 10 minutes). | no |
starting | Accepted on-chain; container being pulled and started. | no |
running | Container running; usage being metered. | no |
completed | Settled with completeJob; charged, refund and usedSeconds set. | yes |
failed | Settled with failJob; full refund. | yes |
cancelled | Not accepted within the accept window; cancelled by the client with cancelJob; full refund. | yes |
reclaimed | Not 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.
{
"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.
curl -X POST https://api.mzgrid.io/v1/jobs/job_7f3a9c2d41/stop -H "Authorization: Bearer $MZG_API_KEY"GET /v1/account
{
"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"
}| Field | Description |
|---|---|
mzgBalance | MZG in your wallet. |
escrowed | MZG currently deposited in escrow for open jobs. |
spent30d | MZG charged over the last 30 days. |
jobsRunning | Jobs in funded, starting or running. |
apiKeys | Number of active API keys. |
termsVersion | Terms of Service version this wallet last accepted (at sign-in or via /providers/terms), or null. |
termsAcceptedAt | When that acceptance was recorded, or null. |