v1

latestOpenAPI 3.1.02026-07-243035381.4 MB

Storage API

Get Walrus storage upload status

/v4/data/storage/upload/{jobId}

0 credits per API call

Get the current status of a Walrus storage upload job. Poll this endpoint after POST /v4/data/storage/upload to track progress through the lifecycle: PENDING → UPLOADING → CERTIFIED.

Once status is CERTIFIED, the response includes downloadUrlByQuiltId and downloadUrlByQuiltPatchId which can be used to retrieve the file from any Walrus aggregator node. The walrusStartEpoch and walrusEndEpoch fields indicate the active storage window (one epoch ≈ 2 weeks).

If status is FAILED, the errorMessage field contains the reason. Failed jobs are not retried automatically — submit a new upload request to try again.

get/v4/data/storage/upload/{jobId}

Path parameters

jobIdstring required

Example:68000000000000000000abcd

The job ID returned by <code>POST /v4/data/storage/upload</code>.

Response

Upload job status.

jobIdstring required

Unique identifier for the upload job.

status'PENDING' | 'UPLOADING' | 'CERTIFIED' | 'FAILED' required

Lifecycle status of a Walrus storage upload job.

filenamestring required

Stored file name on Walrus.

mimeTypestring

MIME type of the uploaded file.

sizeBytesinteger required

File size in bytes.

errorMessagestring

Human-readable error message when status is FAILED.

blobIdstring

Walrus blob ID. Present after the upload is staged.

quiltPatchIdstring

Walrus quilt patch ID. Present after on-chain certification.

suiObjectIdstring

Sui on-chain Blob object ID. Use SuiScan to inspect storage state.

walrusStartEpochinteger

Walrus epoch when storage begins.

walrusEndEpochinteger

Walrus epoch at which storage expires. Renewal window opens one epoch before.

Billing and renewal lifecycle of a certified Walrus blob.

active — blob is live; renewal credits applied on schedule.
pending_initial_charge — certified but first-period credits not yet charged.
pending_renewal_credit — on-chain extend succeeded; scanner posts renewal credits.
pending_decommission — blob past its end epoch; worker will decommission.
pending_instant_delete — immediate on-chain delete queued by user.
decommissioned — blob has been removed from Walrus storage.

noRenewalboolean

When true, the worker will never extend this blob. It expires naturally at walrusEndEpoch.

downloadUrlByQuiltIdstring

Walrus aggregator URL to download the file by blob ID and filename. Present only when status is CERTIFIED and the blob is not decommissioned.

downloadUrlByQuiltPatchIdstring

Walrus aggregator URL to download the file by quilt patch ID. Present only when status is CERTIFIED and the blob is not decommissioned.

createdAtinteger required

Unix timestamp (ms) when the upload job was created.

updatedAtinteger required

Unix timestamp (ms) when the job was last updated.

Example response

{
  "jobId": "68000000000000000000abcd",
  "status": "CERTIFIED",
  "filename": "report.pdf",
  "mimeType": "application/pdf",
  "sizeBytes": 1048576,
  "errorMessage": "RpcError: Service Unavailable",
  "blobId": "mAlStJ4PAJaBuuHEUHotGheikLiTXpQagboGF43bY4s",
  "quiltPatchId": "mAlStJ4PAJaBuuHEUHotGheikLiTXpQagboGF43bY4sBAQCaAg",
  "suiObjectId": "0x1b520353e191083dccad671db585525365e6f5bf70fcf63c7dd8e088ec5c57b6",
  "walrusStartEpoch": 29,
  "walrusEndEpoch": 33,
  "renewalBillingStatus": "active",
  "storageEvents": [
    {
      "type": "registered",
      "txDigest": "4ywoqKo35fVadBsXZQEqQkLr4mY6mHS9MykZU3HmzUKX",
      "at": 1777304790823,
      "epochs": 4
    }
  ],
  "downloadUrlByQuiltId": "https://aggregator.walrus-mainnet.walrus.space/v1/blobs/by-quilt-id/mAlStJ4PAJaBuuHEUHotGheikLiTXpQagboGF43bY4s/report.pdf",
  "downloadUrlByQuiltPatchId": "https://aggregator.walrus-mainnet.walrus.space/v1/blobs/by-quilt-patch-id/mAlStJ4PAJaBuuHEUHotGheikLiTXpQagboGF43bY4sBAQCaAg",
  "createdAt": 1777304790000,
  "updatedAt": 1777304809955
}