Read monthly resource storage subscription

GET/api/v1/storage/Copy URL

Authentication · x-api-key

Disabled by default. Only Admin can enroll an account. Free periods are preserved; prices use a fixed 30-day GB-month and bills use Asia/Shanghai calendar months.

Scope: usage:read

Billing and effects: Free subscription or billing read. Storage accrual is billed separately.

Recovery: Read the current resource before retrying a mutation; do not assume this operation supports Idempotency-Key.

Follow this operation’s workflow → · All permission rules

All endpointsRequestResponsesCode

Request

No request parameters.

Responses

Read the HTTP status and body together. A receipt confirms acceptance; poll the returned Task or product view for terminal execution and media delivery. Example IDs and credit amounts are illustrative, not a price quote.

HTTP 401 · Request rejected; correct the key before retrying

Complete JSON example (optional fields may be omitted).

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

200 OK

application/json

Required, optional and null

Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.

• Response 200 · availableRequired

  boolean

  Whether deployment configuration enables long-term storage with a positive published rate; does not mean this account is enrolled.

• Response 200 · billableBytesRequired

  string

  Sum of bytes in currently open storage-usage intervals, as a decimal integer string.

• Response 200 · billingTimezoneRequired

  string

  Time zone defining the natural monthly billing period.

• Response 200 · billingUnitRequired

  string

  credit-unit / decimal GB / 30 days: 10,000 units per credit and decimal gigabytes, with byte-time prorating.

• Response 200 · chargesRequired

  array<object>

  Up to 24 most recent storage charge periods, ordered by period start descending; use the charges endpoint for pagination.

  1 field

  • Response 200 · charges[]Each item

    object
    8 fields

    • Response 200 · charges[].amountUnitsRequired

      string

      Billed amount as a decimal integer string in credit accounting units (10,000 units = 1 credit). Preserve integer precision.

    • Response 200 · charges[].breakdownRequired

      object

      Monthly storage usage keyed by provider code. Each value is byte-milliseconds, not credits; amountUnits is the billed amount. See Storage billing.

      1 field

      • Response 200 · charges[].breakdown.*Each value

        string

        Accumulated byte-milliseconds for this provider, represented as a decimal integer string.

        Pattern: ^[0-9]+$.

    • Response 200 · charges[].byteMillisecondsRequired

      string

      Accumulated bytes multiplied by stored milliseconds, encoded as a decimal integer string to preserve precision.

    • Response 200 · charges[].fromRequired

      string

      Start of this billing or usage period as an ISO 8601 timestamp.

      Format: date-time.

    • Response 200 · charges[].idRequired

      string

      Identifier of this resource. Keep identifiers for Tasks, product resources and child assets separately; use the ID required by the destination endpoint.

    • Response 200 · charges[].rateUnitsPerGbMonthRequired

      string

      Accepted price in credit accounting units per GB-month (10,000 units = 1 credit). Read the subscription billing unit and period rules.

    • Response 200 · charges[].statusRequired

      string

      State of the object containing this field. Use its listed values; operation acceptance, Task completion and media delivery are separate states.

    • Response 200 · charges[].untilRequired

      string

      Start of this billing or usage period as an ISO 8601 timestamp.

      Format: date-time.

• Response 200 · currentPeriodRequired

  object

  Current natural billing month boundaries and usage accrued through this read; until is the period end, not the accrual measurement time.

  4 fields

  • Response 200 · currentPeriod.accruedUnitsRequired

    string

    Accrued amount for the current period in credit accounting units (10,000 units = 1 credit); this period is not yet the final bill.

  • Response 200 · currentPeriod.byteMillisecondsRequired

    string

    Accumulated bytes multiplied by stored milliseconds, encoded as a decimal integer string to preserve precision.

  • Response 200 · currentPeriod.fromRequired

    string

    Start of this billing or usage period as an ISO 8601 timestamp.

    Format: date-time.

  • Response 200 · currentPeriod.untilRequired

    string

    Start of this billing or usage period as an ISO 8601 timestamp.

    Format: date-time.

• Response 200 · enabledRequired

  boolean

  True only when coverage-version-2 long-term storage is ACTIVE for this account.

• Response 200 · enrollmentCompleteRequired

  boolean

  Whether enrollment of eligible existing assets into unified coverage has completed.

• Response 200 · graceUntilRequired

  string | null

  Start of this billing or usage period as an ISO 8601 timestamp.

  Use a complete option below; the value must satisfy at least one option.

  2 options

  • Response 200 · Option 1 — stringOption

    string

    Start of this billing or usage period as an ISO 8601 timestamp.

    Format: date-time.

  • Response 200 · Option 2 — nullOption

    null

• Response 200 · legacySubscriptionActiveRequired

  boolean

  True when an older coverage-version subscription is still ACTIVE instead of unified long-term coverage.

• Response 200 · pendingAssetsRequired

  number

  Count of retained assets still in ARCHIVING state.

• Response 200 · rateUnitsPerGbMonthRequired

  string

  Accepted price in credit accounting units per GB-month (10,000 units = 1 credit). Read the subscription billing unit and period rules.

• Response 200 · revisionRequired

  number

  Storage policy revision used as expectedRevision for concurrent configuration updates; zero before a subscription exists.

• Response 200 · statusRequired

  string

  State of the object containing this field. Use its listed values; operation acceptance, Task completion and media delivery are separate states.

• Response 200 · totalBytesRequired

  string

  Sum of byte sizes of READY retained assets, as a decimal integer string; not all these bytes are currently billable.

• Response 200 · usageRequired

  array<object>

  Retained asset usage grouped by providerCode and asset status.

  1 field

  • Response 200 · usage[]Each item

    object
    4 fields

    • Response 200 · usage[].bytesRequired

      string

      Byte count as a decimal integer string. Preserve integer precision.

    • Response 200 · usage[].countRequired

      number

      Number of retained asset records in this provider/status group.

    • Response 200 · usage[].providerCodeRequired

      string

      Provider/product code owning this group of retained assets.

    • Response 200 · usage[].statusRequired

      string

      State of the object containing this field. Use its listed values; operation acceptance, Task completion and media delivery are separate states.

• Response 200 · userIdRequired

  string

  Account owner whose long-term storage policy and usage are being read.

401 Unauthorized

application/json

Required, optional and null

Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.

• Response 401 · errorRequired

  object

  Structured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.

  3 fields

  • Response 401 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 401 · error.messageRequired

    string

    Human readable error message

  • Response 401 · error.detailsOptional

    object

    Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

    1 field

    • Response 401 · error.details[key]Each value

      any JSON value

      Key pattern: ^(.*)$.

• Response 401 · successRequired

  false

  Always false for error responses

403 Forbidden

application/json

Required, optional and null

Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.

• Response 403 · errorRequired

  object

  Structured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.

  3 fields

  • Response 403 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 403 · error.messageRequired

    string

    Human readable error message

  • Response 403 · error.detailsOptional

    object

    Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

    1 field

    • Response 403 · error.details[key]Each value

      any JSON value

      Key pattern: ^(.*)$.

• Response 403 · successRequired

  false

  Always false for error responses

429 Too Many Requests

Request allowance or task admission capacity exceeded. Follow Retry-After when present; otherwise wait for active tasks and use bounded backoff. Limits do not guarantee throughput. For SSE, this is the HTTP connection response, not an event.

application/json

Required, optional and null

Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.

• Response 429 · errorRequired

  object

  Structured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.

  3 fields

  • Response 429 · error.codeRequired

    string

    RATE_LIMITED for request and task admission rejections.

  • Response 429 · error.messageRequired

    string

    Human-readable explanation. Wording may change; use the machine-readable code for programmatic decisions.

  • Response 429 · error.detailsOptional

    object

    Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

    9 fields

    • Response 429 · error.details.currentOptional

      integer

      Current count for the rate-limit window identified by policy and scope.

      Minimum: 0.

    • Response 429 · error.details.inFlightOptional

      integer

      Current accepted tasks counted against the relevant account or API-key admission limit.

      Minimum: 0.

    • Response 429 · error.details.limitOptional

      integer

      Maximum count allowed by this response context. A limit is not a throughput guarantee.

      Minimum: 0.

    • Response 429 · error.details.policyOptional

      "operation" | "query"

      Allowance bucket: query for resource reads, operation for task-producing or operation requests. See the rate-limit response headers.

    • Response 429 · error.details.retryAfterSecOptional

      integer

      Suggested delay in seconds before another request. Honor the Retry-After header when present; use bounded backoff.

      Minimum: 1.

    • Response 429 · error.details.scopeOptional

      "user" | "api-key" | "ip" | "apiKey"

      Entity whose allowance was exceeded, such as the user, API key or IP address.

    • Response 429 · error.details.tierOptional

      "FREE" | "PREMIUM" | "ENTERPRISE"

      Account allowance tier used for this admission or rate-limit decision.

    • Response 429 · error.details.typeOptional

      "rps" | "daily" | "monthly"

      Admission limit that rejected the request: rps (continuously refilled requests-per-second bucket), daily or monthly UTC request budget. Interpret with policy, scope and retryAfterSec.

    • Response 429 · error.details[key]Each value

      any JSON value

      Key pattern: ^(.*)$.

• Response 429 · successRequired

  false

  Whether this response reports a successful action; false accompanies the structured error object.

  Default: false.

500 Internal Server Error

application/json

Required, optional and null

Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.

• Response 500 · errorRequired

  object

  Structured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.

  3 fields

  • Response 500 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 500 · error.messageRequired

    string

    Human readable error message

  • Response 500 · error.detailsOptional

    object

    Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

    1 field

    • Response 500 · error.details[key]Each value

      any JSON value

      Key pattern: ^(.*)$.

• Response 500 · successRequired

  false

  Always false for error responses

Request example

Wrap lines

cURL

curl --globoff --request GET \
  --url 'https://api.omnapi.com/api/v1/storage/' \
  --header "x-api-key: $OMNAPI_KEY"

Node.js

const response = await fetch("https://api.omnapi.com/api/v1/storage/", {
  method: "GET",
  headers: {
    "x-api-key": process.env.OMNAPI_KEY,
  },
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.text());

Python

import os
import requests

response = requests.request(
    "GET", "https://api.omnapi.com/api/v1/storage/",
    headers={
        "x-api-key": os.environ["OMNAPI_KEY"],
    },
    timeout=60,
)
response.raise_for_status()
print(response.text)

Replace URL placeholders such as {taskId} with IDs from actual responses, and set the header environment variables shown above.

Workflow and next steps → · Recover an uncertain request

Interactive API Explorer → · OpenAPI JSON