{
  "openapi": "3.0.1",
  "info": {
    "title": "Suno Scraper - Songs, Playlists, Creators & Lyrics",
    "description": "Collect public Suno music data: songs with lyrics, style tags, model version, play and like counts, audio, video and cover art links, plus playlist and creator records. Choose the curated Explore sections, specific playlists, or a creator's full public catalogue.",
    "version": "0.2",
    "x-build-id": "OTuWPyuCkAYWHy9Uf"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/abotapi~suno-music-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-abotapi-suno-music-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/abotapi~suno-music-scraper/runs": {
      "post": {
        "operationId": "runs-sync-abotapi-suno-music-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/abotapi~suno-music-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-abotapi-suno-music-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "required": [
          "mode"
        ],
        "properties": {
          "mode": {
            "title": "Mode",
            "enum": [
              "explore",
              "playlists",
              "profiles",
              "urls"
            ],
            "type": "string",
            "description": "Where to collect from: the curated Explore sections, specific playlists, creator profiles, or any mix of Suno links.",
            "default": "explore"
          },
          "exploreFeeds": {
            "title": "Sections to read (optional)",
            "type": "array",
            "description": "Only read when mode = explore. Leave empty to cover every curated section the discovery page currently offers. Fill it to pin specific sections, either by their section id or by a playlist id.",
            "items": {
              "type": "string"
            }
          },
          "playlistUrls": {
            "title": "Playlist links or ids",
            "type": "array",
            "description": "Only read when mode = playlists. Paste playlist page links or bare playlist ids. Each playlist is read in full, up to the record cap; a link ending in ?page=N starts reading at page N.",
            "default": [
              "https://suno.com/playlist/0d597d0c-cdb2-4f9c-b4da-57931929f0d0"
            ],
            "items": {
              "type": "string"
            }
          },
          "profileUrls": {
            "title": "Profile links or handles",
            "type": "array",
            "description": "Only read when mode = profiles. Paste creator profile links or bare handles such as @suno. Each creator's public catalogue is read in full, up to the record cap.",
            "default": [
              "https://suno.com/@suno"
            ],
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Suno links (any page type)",
            "type": "array",
            "description": "Only read when mode = urls. Paste any mix of playlist links (with or without ?page=N), creator profile links (@handle, optional ?sort=), the /explore page, and song links. Unsupported links get a warning, never a silent zero. Left untouched, one example of each shape is scraped.",
            "default": [
              "https://suno.com/playlist/0d597d0c-cdb2-4f9c-b4da-57931929f0d0",
              "https://suno.com/playlist/0d597d0c-cdb2-4f9c-b4da-57931929f0d0?page=2",
              "https://suno.com/@suno",
              "https://suno.com/@suno?sort=created_at",
              "https://suno.com/explore",
              "https://suno.com/song/12ff82e8-88f7-407a-969d-dd1023df26a3"
            ],
            "items": {
              "type": "string"
            }
          },
          "profileSortBy": {
            "title": "Profile ordering",
            "enum": [
              "upvote_count",
              "created_at",
              "play_count"
            ],
            "type": "string",
            "description": "Order in which a creator's songs and playlists are returned.",
            "default": "upvote_count"
          },
          "followProfilePlaylists": {
            "title": "Also read the playlists linked on the profile",
            "type": "boolean",
            "description": "After a creator's own songs, also include every public playlist listed on that creator's profile.",
            "default": false
          },
          "styleTag": {
            "title": "Style tag contains",
            "type": "string",
            "description": "Keep only songs whose style tags contain this text (case-insensitive), for example synthwave. Songs are filtered after they are read, so a narrow filter reads more pages for the same number of rows."
          },
          "modelVersion": {
            "title": "Model version",
            "type": "string",
            "description": "Keep only songs made with this model, for example v4 or v3.5 (matches the model version or model name)."
          },
          "minPlayCount": {
            "title": "Minimum play count",
            "minimum": 0,
            "type": "integer",
            "description": "Keep only songs played at least this many times. Leave empty for no minimum."
          },
          "createdAfter": {
            "title": "Created on or after",
            "type": "string",
            "description": "Keep only songs created on or after this date (YYYY-MM-DD)."
          },
          "isInstrumental": {
            "title": "Instrumental",
            "enum": [
              "any",
              "yes",
              "no"
            ],
            "type": "string",
            "description": "Keep only instrumental songs (yes), only songs with vocals (no), or all songs (any). Songs without the flag are dropped when you pick yes or no.",
            "default": "any"
          },
          "includeLyrics": {
            "title": "Include lyrics",
            "type": "boolean",
            "description": "Include the full lyric sheet on every song record. Turn off for a much smaller dataset when you only need titles, styles and counts.",
            "default": true
          },
          "includeComments": {
            "title": "Include comments",
            "type": "boolean",
            "description": "Add each song's public comments (with replies) to the song record as a nested comments list. No extra records are produced. Costs one extra request per song, so runs are slower.",
            "default": false
          },
          "maxCommentsPerSong": {
            "title": "Max comments per song",
            "minimum": 1,
            "maximum": 200,
            "type": "integer",
            "description": "Only used when Include comments is on. Newest top-level comments first; replies come nested inside their comment.",
            "default": 20
          },
          "maxItems": {
            "title": "Max records",
            "minimum": 0,
            "type": "integer",
            "description": "Stop after this many records across the whole run (0 = no limit). Songs, playlist headers, creator profiles and contests all count as records.",
            "default": 20
          },
          "maxPages": {
            "title": "Max pages per source",
            "minimum": 0,
            "type": "integer",
            "description": "Optional limit on how many pages are read for any single playlist, profile or section (0 = no limit). A hard cap of 200 pages per source always applies, so the record cap above is the real limit.",
            "default": 0
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Connection used for every request. The default works on every plan.",
            "default": {
              "useApifyProxy": true
            }
          },
          "resumeFromRunId": {
            "title": "Continue a previous run",
            "type": "string",
            "description": "Paste the run id (or dataset id) of an earlier run of this Actor to continue it. Records that run already returned are skipped, so an interrupted large collection can finish without paying for the same rows twice. Leave empty for a normal run."
          },
          "incrementalMode": {
            "title": "Recurring updates (only return what changed)",
            "type": "boolean",
            "description": "Turn this on for daily or weekly monitoring. The first run returns everything as NEW. Later runs return only NEW, UPDATED and REAPPEARED records, each labelled in a changeType column. Note that play, like and comment counts move constantly on an active catalogue, so a record whose only difference is a counter still counts as UPDATED. Leave off for a normal one-off run.",
            "default": false
          },
          "stateKey": {
            "title": "State key (optional, recurring updates only)",
            "type": "string",
            "description": "Optional. Name this monitoring campaign to keep its memory stable, or to deliberately share one memory across differently configured runs. Leave empty and the memory is keyed on the run setup automatically."
          },
          "emitUnchanged": {
            "title": "Also return unchanged records (recurring updates only)",
            "type": "boolean",
            "description": "Off by default. Turn on to also return records that have not changed since the last run, labelled UNCHANGED. This returns, and bills, rows you already have.",
            "default": false
          },
          "emitExpired": {
            "title": "Also return records that are gone (recurring updates only)",
            "type": "boolean",
            "description": "Off by default. Turn on to also return records that were present before and are no longer found, labelled EXPIRED. Only produced when a run covered its whole setup, so a capped or continued run never reports records as gone. This returns, and bills, extra rows.",
            "default": false
          },
          "ignoreFieldsForChanges": {
            "title": "Ignore fields when detecting changes (incremental mode only)",
            "type": "array",
            "description": "Recurring updates only. Field names (for example playCount, upvoteCount, commentCount) whose changes should NOT make a record count as UPDATED. The fields still appear in every returned row. Run-specific fields (scrapedAt and the source* keys) are always ignored. Leave empty to treat every other change as an update.",
            "items": {
              "type": "string"
            }
          },
          "mcpConnectors": {
            "title": "Pipe results into your apps (optional)",
            "type": "array",
            "description": "Optionally send results into the apps you already use, via Model Context Protocol (MCP) connectors. Authorize one under Apify, Settings, API & Integrations, then select it here. Notion gets a rich page-per-item export; other connectors get a best-effort write or digest. Leave empty to skip; never changes the dataset output.",
            "items": {
              "type": "string"
            }
          },
          "notionParentPageUrl": {
            "title": "Notion parent page (Notion connector only)",
            "type": "string",
            "description": "URL or id of the Notion page under which item pages are created. Required to enable the Notion export; ignored by other connectors."
          },
          "maxNotifyListings": {
            "title": "Max items to export per connector",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "Cap on items written to each connector per run. Does not affect the dataset.",
            "default": 50
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}