Sign in

v1

latestOpenAPI 3.1.02026-07-243035381.4 MB
Storage API

List Walrus storage uploads

/v4/data/storage/uploads

0 credits per API call

List all upload jobs for the current API key, ordered by most recently created. Use limit and offset to paginate through results.

get/v4/data/storage/uploads

Query parameters

limitinteger
Example:20

Number of results to return. Range 1–100, default 50.

offsetinteger

Number of results to skip for pagination. Maximum 10 000.

Response

List of upload jobs.

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.

renewalBillingStatus'active' | 'pending_initial_charge' | 'pending_renewal_credit' | 'pending_decommission' | 'pending_instant_delete' | 'decommissioned'

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
  }
]