List Suno generations

GET/api/v1/suno/generationsCopy URL

Authentication · x-api-key

Cursor-paginated product history. The cursor is opaque; do not construct it client-side.

All endpointsRequestResponsesCode

Request

limitquery · Optional

number

Maximum number of items to return.

Minimum: 1. Maximum: 100.

cursorquery · Optional

string

Opaque pagination cursor returned as nextCursor; omit it on the first page.

Responses

200 OK

application/json

Unknown fields are not accepted.

• Response 200 · hasMoreRequired

  boolean

• Response 200 · itemsRequired

  array<object>
  1 field

  • Response 200 · items[]Each item

    object

    Unknown fields are not accepted.

    19 fields

    • Response 200 · items[].autoFinalizeRequired

      boolean

    • Response 200 · items[].billingRequired

      object

      Unknown fields are not accepted.

      5 fields

      • Response 200 · items[].billing.creditsChargedRequired

        number | null

        May be null. Must match at least one alternative.

        2 fields / alternatives

        • Response 200 · items[].billing.creditsCharged · anyOf 1Alternative

          number

          Minimum: 0.

          1 field

          • Response 200 · items[].billing.creditsCharged · anyOf 1See schema

            number

            Expand this value in the interactive reference.

            Minimum: 0.

        • Response 200 · items[].billing.creditsCharged · anyOf 2Alternative

          null
          1 field

          • Response 200 · items[].billing.creditsCharged · anyOf 2See schema

            null

            Expand this value in the interactive reference.

      • Response 200 · items[].billing.creditsRequiredRequired

        number

        Minimum: 0.

      • Response 200 · items[].billing.pricingRequired

        object | null

        May be null. Must match at least one alternative.

        2 fields / alternatives

        • Response 200 · items[].billing.pricing · anyOf 1Alternative

          object

          Unknown fields are not accepted.

          1 field

          • Response 200 · items[].billing.pricing · anyOf 1See schema

            object

            Expand this value in the interactive reference.

            Unknown fields are not accepted.

        • Response 200 · items[].billing.pricing · anyOf 2Alternative

          null
          1 field

          • Response 200 · items[].billing.pricing · anyOf 2See schema

            null

            Expand this value in the interactive reference.

      • Response 200 · items[].billing.refundedRequired

        boolean

      • Response 200 · items[].billing.settlementStatusRequired

        "PENDING" | "CHARGED" | "REFUNDED"

    • Response 200 · items[].clipsRequired

      array<object>
      1 field

      • Response 200 · items[].clips[]Each item

        object

        Unknown fields are not accepted.

        23 fields

        • Response 200 · items[].clips[].accessLevelRequired

          "owned" | "shared" | "external"

          Read projection only. owned returns the full public Clip contract; shared is public or remixable; external is merely readable by clipId. This value does not grant derive or export permission.

          1 field

          • Response 200 · items[].clips[].accessLevelSee schema

            "owned" | "shared" | "external"

            Expand this value in the interactive reference.

        • Response 200 · items[].clips[].audioUrlRequired

          string | null

          May be null. Must match at least one alternative.

          1 field

          • Response 200 · items[].clips[].audioUrlSee schema

            string | null

            Expand this value in the interactive reference.

            May be null. Must match at least one alternative.

        • Response 200 · items[].clips[].clipIdRequired

          string

          Suno clip identifier (`mid`); do not substitute an OmnAPI resource identifier.

          1 field

          • Response 200 · items[].clips[].clipIdSee schema

            string

            Expand this value in the interactive reference.

        • Response 200 · items[].clips[].createdAtRequired

          string | null

          May be null. Must match at least one alternative.

          1 field

          • Response 200 · items[].clips[].createdAtSee schema

            string | null

            Expand this value in the interactive reference.

            May be null. Must match at least one alternative.

        • Response 200 · items[].clips[].deliveryStatusRequired

          "submitted" | "queued" | "streaming" | "complete" | "error"
          1 field

          • Response 200 · items[].clips[].deliveryStatusSee schema

            "submitted" | "queued" | "streaming" | "complete" | "error"

            Expand this value in the interactive reference.

        • Response 200 · items[].clips[].durationRequired

          number | null

          May be null. Must match at least one alternative.

          1 field

          • Response 200 · items[].clips[].durationSee schema

            number | null

            Expand this value in the interactive reference.

            May be null. Must match at least one alternative.

        • Response 200 · items[].clips[].errorCodeRequired

          string | null

          May be null. Must match at least one alternative.

          1 field

          • Response 200 · items[].clips[].errorCodeSee schema

            string | null

            Expand this value in the interactive reference.

            May be null. Must match at least one alternative.

        • Response 200 · items[].clips[].errorMessageRequired

          string | null

          May be null. Must match at least one alternative.

          1 field

          • Response 200 · items[].clips[].errorMessageSee schema

            string | null

            Expand this value in the interactive reference.

            May be null. Must match at least one alternative.

        • Response 200 · items[].clips[].imageUrlRequired

          string | null

          May be null. Must match at least one alternative.

          1 field

          • Response 200 · items[].clips[].imageUrlSee schema

            string | null

            Expand this value in the interactive reference.

            May be null. Must match at least one alternative.

        • Response 200 · items[].clips[].indexRequired

          number

          Minimum: 0.

          1 field

          • Response 200 · items[].clips[].indexSee schema

            number

            Expand this value in the interactive reference.

            Minimum: 0.

        • Response 200 · items[].clips[].instrumentalRequired

          boolean | null

          May be null. Must match at least one alternative.

          1 field

          • Response 200 · items[].clips[].instrumentalSee schema

            boolean | null

            Expand this value in the interactive reference.

            May be null. Must match at least one alternative.

        • Response 200 · items[].clips[].majorModelVersionRequired

          string | null

          May be null. Must match at least one alternative.

          1 field

          • Response 200 · items[].clips[].majorModelVersionSee schema

            string | null

            Expand this value in the interactive reference.

            May be null. Must match at least one alternative.

        • Response 200 · items[].clips[].modelRequired

          string | null

          May be null. Must match at least one alternative.

          1 field

          • Response 200 · items[].clips[].modelSee schema

            string | null

            Expand this value in the interactive reference.

            May be null. Must match at least one alternative.

        • Response 200 · items[].clips[].modelCodeRequired

          string | null

          May be null. Must match at least one alternative.

          1 field

          • Response 200 · items[].clips[].modelCodeSee schema

            string | null

            Expand this value in the interactive reference.

            May be null. Must match at least one alternative.

        • Response 200 · items[].clips[].playableRequired

          boolean
          1 field

          • Response 200 · items[].clips[].playableSee schema

            boolean

            Expand this value in the interactive reference.

        • Response 200 · items[].clips[].playbackRequired

          object

          Unknown fields are not accepted.

          1 field

          • Response 200 · items[].clips[].playbackSee schema

            object

            Expand this value in the interactive reference.

            Unknown fields are not accepted.

        • Response 200 · items[].clips[].promptRequired

          string | null

          May be null. Must match at least one alternative.

          1 field

          • Response 200 · items[].clips[].promptSee schema

            string | null

            Expand this value in the interactive reference.

            May be null. Must match at least one alternative.

        • Response 200 · items[].clips[].providerModelNameRequired

          string | null

          May be null. Must match at least one alternative.

          1 field

          • Response 200 · items[].clips[].providerModelNameSee schema

            string | null

            Expand this value in the interactive reference.

            May be null. Must match at least one alternative.

        • Response 200 · items[].clips[].roleRequired

          "candidate" | "final"
          1 field

          • Response 200 · items[].clips[].roleSee schema

            "candidate" | "final"

            Expand this value in the interactive reference.

        • Response 200 · items[].clips[].tagsRequired

          string | null

          May be null. Must match at least one alternative.

          1 field

          • Response 200 · items[].clips[].tagsSee schema

            string | null

            Expand this value in the interactive reference.

            May be null. Must match at least one alternative.

        • Response 200 · items[].clips[].titleRequired

          string | null

          May be null. Must match at least one alternative.

          1 field

          • Response 200 · items[].clips[].titleSee schema

            string | null

            Expand this value in the interactive reference.

            May be null. Must match at least one alternative.

        • Response 200 · items[].clips[].updatedAtRequired

          string | null

          May be null. Must match at least one alternative.

          1 field

          • Response 200 · items[].clips[].updatedAtSee schema

            string | null

            Expand this value in the interactive reference.

            May be null. Must match at least one alternative.

        • Response 200 · items[].clips[].videoUrlRequired

          string | null

          May be null. Must match at least one alternative.

          1 field

          • Response 200 · items[].clips[].videoUrlSee schema

            string | null

            Expand this value in the interactive reference.

            May be null. Must match at least one alternative.

    • Response 200 · items[].createdAtRequired

      string

      Format: date-time.

    • Response 200 · items[].deliveryStatusRequired

      "submitted" | "queued" | "streaming" | "complete" | "error" | null

      May be null. Must match at least one alternative.

      2 fields / alternatives

      • Response 200 · items[].deliveryStatus · anyOf 1Alternative

        "submitted" | "queued" | "streaming" | "complete" | "error"

        Must match at least one alternative.

        5 fields / alternatives

        • Response 200 · items[].deliveryStatus · anyOf 1 · anyOf 1Alternative

          "submitted"
          1 field

          • Response 200 · items[].deliveryStatus · anyOf 1 · anyOf 1See schema

            "submitted"

            Expand this value in the interactive reference.

        • Response 200 · items[].deliveryStatus · anyOf 1 · anyOf 2Alternative

          "queued"
          1 field

          • Response 200 · items[].deliveryStatus · anyOf 1 · anyOf 2See schema

            "queued"

            Expand this value in the interactive reference.

        • Response 200 · items[].deliveryStatus · anyOf 1 · anyOf 3Alternative

          "streaming"
          1 field

          • Response 200 · items[].deliveryStatus · anyOf 1 · anyOf 3See schema

            "streaming"

            Expand this value in the interactive reference.

        • Response 200 · items[].deliveryStatus · anyOf 1 · anyOf 4Alternative

          "complete"
          1 field

          • Response 200 · items[].deliveryStatus · anyOf 1 · anyOf 4See schema

            "complete"

            Expand this value in the interactive reference.

        • Response 200 · items[].deliveryStatus · anyOf 1 · anyOf 5Alternative

          "error"
          1 field

          • Response 200 · items[].deliveryStatus · anyOf 1 · anyOf 5See schema

            "error"

            Expand this value in the interactive reference.

      • Response 200 · items[].deliveryStatus · anyOf 2Alternative

        null

    • Response 200 · items[].failureReasonRequired

      string | null

      May be null. Must match at least one alternative.

      2 fields / alternatives

      • Response 200 · items[].failureReason · anyOf 1Alternative

        string

      • Response 200 · items[].failureReason · anyOf 2Alternative

        null

    • Response 200 · items[].finalClipIdRequired

      string | null

      May be null. Must match at least one alternative.

      2 fields / alternatives

      • Response 200 · items[].finalClipId · anyOf 1Alternative

        string

      • Response 200 · items[].finalClipId · anyOf 2Alternative

        null

    • Response 200 · items[].finalUrlRequired

      string | null

      May be null. Must match at least one alternative.

      2 fields / alternatives

      • Response 200 · items[].finalUrl · anyOf 1Alternative

        string

      • Response 200 · items[].finalUrl · anyOf 2Alternative

        null

    • Response 200 · items[].generationIdRequired

      string

      Canonical OmnAPI Suno product ID. It equals the originating taskId.

    • Response 200 · items[].partialFailureRequired

      boolean

      True when the generation completed with at least one successful clip and at least one failed clip.

    • Response 200 · items[].phaseRequired

      "accepted" | "generating" | "finalizing" | "completed" | "failed"

    • Response 200 · items[].progressRequired

      number

      Minimum: 0. Maximum: 100.

    • Response 200 · items[].refundableRequired

      boolean

    • Response 200 · items[].retryableRequired

      boolean

    • Response 200 · items[].statusRequired

      "PENDING" | "PROCESSING" | "COMPLETED" | "FAILED" | "CANCELLED"

      Default: "PENDING".

    • Response 200 · items[].taskIdRequired

      string

    • Response 200 · items[].updatedAtRequired

      string

      Format: date-time.

    • Response 200 · items[].versionRequired

      number

      Minimum: 0.

    • Response 200 · items[].warningCodesRequired

      array<string>
      1 field

      • Response 200 · items[].warningCodes[]Each item

        string

• Response 200 · nextCursorRequired

  string | null

  May be null. Must match at least one alternative.

  2 fields / alternatives

  • Response 200 · nextCursor · anyOf 1Alternative

    string

  • Response 200 · nextCursor · anyOf 2Alternative

    null

400 Bad Request

application/json

• Response 400 · errorRequired

  object
  3 fields

  • Response 400 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 400 · error.messageRequired

    string

    Human readable error message

  • Response 400 · error.detailsOptional

    object

    Additional error details (optional)

• Response 400 · successRequired

  false

  Always false for error responses

401 Unauthorized

application/json

• Response 401 · errorRequired

  object
  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

    Additional error details (optional)

• Response 401 · successRequired

  false

  Always false for error responses

403 Forbidden

Forbidden: the API key lacks the required scope or its IP policy rejects this request.

application/json

• Response 403 · errorRequired

  object
  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

    Additional error details (optional)

• 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

• Response 429 · errorRequired

  object
  3 fields

  • Response 429 · error.codeRequired

    string

    RATE_LIMITED for request and task admission rejections.

  • Response 429 · error.messageRequired

    string

  • Response 429 · error.detailsOptional

    object

    Optional and scope-dependent. Request limits supply scope/policy/type/limit/current/retryAfterSec. Task admission supplies inFlight/limit/tier, plus scope=apiKey for a key cap. IP rejection can omit details. In-flight rejection does not promise Retry-After.

    8 fields

    • Response 429 · error.details.currentOptional

      integer

      Minimum: 0.

    • Response 429 · error.details.inFlightOptional

      integer

      Minimum: 0.

    • Response 429 · error.details.limitOptional

      integer

      Minimum: 0.

    • Response 429 · error.details.policyOptional

      "operation" | "query"

    • Response 429 · error.details.retryAfterSecOptional

      integer

      Minimum: 1.

    • Response 429 · error.details.scopeOptional

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

    • Response 429 · error.details.tierOptional

      "FREE" | "PREMIUM" | "ENTERPRISE"

    • Response 429 · error.details.typeOptional

      "rps" | "daily" | "monthly"

• Response 429 · successRequired

  false

  Default: false.

500 Internal Server Error

application/json

• Response 500 · errorRequired

  object
  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

    Additional error details (optional)

• 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/suno/generations' \
  --header "x-api-key: $OMNAPI_KEY"

Node.js

const response = await fetch("https://api.omnapi.com/api/v1/suno/generations", {
  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/suno/generations",
    headers={
        "x-api-key": os.environ["OMNAPI_KEY"],
    },
    timeout=60,
)
response.raise_for_status()
print(response.text)

Set URL and header variables.

Interactive API Explorer → · OpenAPI JSON