REST API reference

SoundCloud API

14 endpoints for SoundCloud. Each one is a POST with a JSON body, called with your API key.

Base URL
https://cotlet.dev/api/v1/soundcloud
Connects with
Your own SoundCloud account (Artist Pro for audience Insights and scheduled releases)
Integration page
SoundCloud
SoundCloud Endpoints
Endpoint Access Description
list_tracks read Your uploads, newest first, with privacy, release date and lifetime counts.
get_track read Full track details: title, description, genre, tags, privacy, secret link, comment and download settings and counts.
get_insights read Plays, likes, comments, reposts and downloads for a period, for your profile or one track, with top tracks.
get_audience read Top 50 listeners, countries, cities or play sources for a period. Needs Artist Pro.
list_comments read Comments on your tracks, newest first, with author, text, waveform timestamp and whether you replied.
list_conversations read Your direct message threads with the other person, last message and unread state.
upload_track write Upload an audio file as a private track. Nobody sees it until you make it public or it is released.
update_track write Change the title, description, genre, tags, artwork or comment and download settings of a track.
schedule_release write Set when a private track goes public and lands in followers' feeds. Needs Artist Pro.
set_track_privacy write Make a track public now, or private with a secret link you can share.
create_playlist write New playlist from your tracks. Private by default, with a secret link.
reply_to_comment write Reply as you under a comment on your track.
delete_comment write Permanently remove a comment from your track, optionally reporting it as spam.
send_message write Send a direct message to one user, optionally with one of your tracks attached.

List tracks

read

POST https://cotlet.dev/api/v1/soundcloud/list_tracks

Lists the tracks on your profile, newest first. Privacy is public, private or scheduled, and scheduled tracks show their release time. Counts are lifetime plays, likes, comments and reposts; get_insights returns them for a period. Pages hold up to 200 tracks; pass next_cursor back as cursor.

Parameters

Parameters: list_tracks
NameTypeDescription
privacy enum all, public, private or scheduled. Default: all.
limit integer 1 to 200. Default: 50.
cursor string Next page cursor from the previous call.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/soundcloud/list_tracks \
  -H "Authorization: Bearer $COTLET_API_KEY"
Python
result = client.call("soundcloud", "list_tracks")
Node.js
const result = await cotlet.call('soundcloud', 'list_tracks');
CLI
cotlet call soundcloud list_tracks

Example response

{
  "tracks": [
    {
      "track_id": "2148839017",
      "title": "Night Drive",
      "privacy": "scheduled",
      "release_at": "2026-10-16T18:00:00+02:00",
      "genre": "House",
      "plays": 0,
      "likes": 0,
      "comments": 0,
      "reposts": 0,
      "url": "https://soundcloud.com/yourname/night-drive"
    },
    {
      "track_id": "2141120034",
      "title": "Harbour Lights",
      "privacy": "public",
      "release_at": null,
      "genre": "House",
      "plays": 4210,
      "likes": 188,
      "comments": 31,
      "reposts": 42,
      "url": "https://soundcloud.com/yourname/harbour-lights"
    }
  ],
  "next_cursor": null
}

Get track

read

POST https://cotlet.dev/api/v1/soundcloud/get_track

Returns one of your tracks with its full description, tags and privacy. A private track includes its secret link. Comment and download settings show whether comments are on and whether the track can be downloaded.

Parameters

Parameters: get_track
NameTypeDescription
track_id required string Track ID from list_tracks.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/soundcloud/get_track \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"track_id":"track_8c41d2"}'
Python
result = client.call("soundcloud", "get_track", {"track_id":"track_8c41d2"})
Node.js
const result = await cotlet.call('soundcloud', 'get_track', {"track_id":"track_8c41d2"});
CLI
cotlet call soundcloud get_track --data '{"track_id":"track_8c41d2"}'

Example response

{
  "track_id": "2148839017",
  "title": "Night Drive",
  "description": "Late-night deep house, 124 BPM.",
  "genre": "House",
  "tags": [
    "deep house",
    "night"
  ],
  "privacy": "private",
  "secret_url": "https://soundcloud.com/yourname/night-drive/s-Ab12Cd34Ef",
  "comments_enabled": true,
  "downloadable": false,
  "plays": 0,
  "likes": 0,
  "comments": 0,
  "reposts": 0
}

Get Insights

read

POST https://cotlet.dev/api/v1/soundcloud/get_insights

Returns the numbers SoundCloud shows in Insights for the period you set, for your whole profile or one track. The response lists top tracks by plays, highest first. Available to every account. Counts match the Insights page at the time of the call.

Parameters

Parameters: get_insights
NameTypeDescription
from date Start of the period, inclusive.
to date End of the period, inclusive. Default: today.
track_id string Limit to one track. Default: all tracks.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/soundcloud/get_insights \
  -H "Authorization: Bearer $COTLET_API_KEY"
Python
result = client.call("soundcloud", "get_insights")
Node.js
const result = await cotlet.call('soundcloud', 'get_insights');
CLI
cotlet call soundcloud get_insights

Example response

{
  "from": "2026-10-05",
  "to": "2026-10-11",
  "totals": {
    "plays": 1840,
    "likes": 96,
    "comments": 14,
    "reposts": 22,
    "downloads": 5
  },
  "top_tracks": [
    {
      "track_id": "2141120034",
      "title": "Harbour Lights",
      "plays": 1210
    },
    {
      "track_id": "2139904418",
      "title": "Slow Burn",
      "plays": 630
    }
  ]
}

Get audience

read

POST https://cotlet.dev/api/v1/soundcloud/get_audience

Returns the top 50 for one breakdown and any period you set, highest first. Top listeners include only signed-in listeners, and plays from your own account are not counted. Sources show where plays came from, such as the SoundCloud app, a playlist or an embed on another website. Needs Artist Pro; other accounts get a permission error.

Parameters

Parameters: get_audience
NameTypeDescription
breakdown required enum top_listeners, countries, cities or sources.
from date Start of the period, inclusive.
to date End of the period, inclusive. Default: today.
track_id string Limit to one track. Default: all tracks.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/soundcloud/get_audience \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"breakdown":"cities","from":"2026-04-01","to":"2026-09-30"}'
Python
result = client.call("soundcloud", "get_audience", {"breakdown":"cities","from":"2026-04-01","to":"2026-09-30"})
Node.js
const result = await cotlet.call('soundcloud', 'get_audience', {"breakdown":"cities","from":"2026-04-01","to":"2026-09-30"});
CLI
cotlet call soundcloud get_audience --data '{"breakdown":"cities","from":"2026-04-01","to":"2026-09-30"}'

Example response

{
  "breakdown": "countries",
  "from": "2026-07-01",
  "to": "2026-09-30",
  "items": [
    {
      "name": "Germany",
      "plays": 5120
    },
    {
      "name": "United Kingdom",
      "plays": 3874
    },
    {
      "name": "United States",
      "plays": 2950
    }
  ]
}

List comments

read

POST https://cotlet.dev/api/v1/soundcloud/list_comments

Lists comments on your tracks, newest first. Each has the author, the text, the position on the waveform where it was left and a flag for whether you already replied. Use since to read only what came in after your last check and unanswered_only to skip answered ones.

Parameters

Parameters: list_comments
NameTypeDescription
track_id string Limit to one track. Default: all tracks.
since date Only comments posted on or after this date.
unanswered_only boolean Skip comments you already replied to.
cursor string Next page cursor from the previous call.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/soundcloud/list_comments \
  -H "Authorization: Bearer $COTLET_API_KEY"
Python
result = client.call("soundcloud", "list_comments")
Node.js
const result = await cotlet.call('soundcloud', 'list_comments');
CLI
cotlet call soundcloud list_comments

Example response

{
  "comments": [
    {
      "comment_id": "3347102215",
      "track_id": "2141120034",
      "author": "Mira K.",
      "body": "That bass line!",
      "at_seconds": 83,
      "created_at": "2026-10-09T20:14:00Z",
      "replied": false
    },
    {
      "comment_id": "3347102498",
      "track_id": "2141120034",
      "author": "promo_bot_77",
      "body": "Follow me for free beats http://spam.example",
      "at_seconds": 12,
      "created_at": "2026-10-09T21:02:00Z",
      "replied": false
    }
  ],
  "next_cursor": null
}

List conversations

read

POST https://cotlet.dev/api/v1/soundcloud/list_conversations

Lists your direct message threads, most recent first, with the other person, the last messages and whether the thread is unread. Set unread_only to see only what needs an answer. Pass conversation_id or the person's profile URL to send_message.

Parameters

Parameters: list_conversations
NameTypeDescription
unread_only boolean Only threads with unread messages.
limit integer 1 to 50. Default: 20.
cursor string Next page cursor from the previous call.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/soundcloud/list_conversations \
  -H "Authorization: Bearer $COTLET_API_KEY"
Python
result = client.call("soundcloud", "list_conversations")
Node.js
const result = await cotlet.call('soundcloud', 'list_conversations');
CLI
cotlet call soundcloud list_conversations

Example response

{
  "conversations": [
    {
      "conversation_id": "cv_5521",
      "with": {
        "name": "Jonas Weber",
        "profile_url": "https://soundcloud.com/jonas-weber"
      },
      "unread": true,
      "last_message": "Love Night Drive. Want to do a remix?",
      "updated_at": "2026-10-10T08:30:00Z"
    }
  ],
  "next_cursor": null
}

Upload track

write

POST https://cotlet.dev/api/v1/soundcloud/upload_track

Uploads an audio file from a URL and creates a private track with the details you give. Private tracks are hidden from followers and search, and reached only through a secret link. upload_track reaches no one and one call to set_track_privacy or a delete in SoundCloud undoes it, so it runs without asking first.

Parameters

Parameters: upload_track
NameTypeDescription
file_url required string URL of the audio file.
title required string Track title.
description string Track description.
genre string Genre, e.g. House.
tags string[] Additional tags.
artwork_url string URL of a square image for the artwork.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/soundcloud/upload_track \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_url":"https://example.com","title":"title"}'
Python
result = client.call("soundcloud", "upload_track", {"file_url":"https://example.com","title":"title"})
Node.js
const result = await cotlet.call('soundcloud', 'upload_track', {"file_url":"https://example.com","title":"title"});
CLI
cotlet call soundcloud upload_track --data '{"file_url":"https://example.com","title":"title"}'

Example response

{
  "track_id": "2148839017",
  "title": "Night Drive",
  "privacy": "private",
  "status": "processing",
  "secret_url": "https://soundcloud.com/yourname/night-drive/s-Ab12Cd34Ef"
}

Update track details

write

POST https://cotlet.dev/api/v1/soundcloud/update_track

Changes the fields you pass and leaves the rest as they are. The audio file itself cannot be replaced after upload. Changes show on the public track page right away. update_track reaches no one directly and the old values can be set again with one call, so it runs without asking first.

Parameters

Parameters: update_track
NameTypeDescription
track_id required string Track ID from list_tracks.
fields required object Any of title, description, genre, tags, artwork_url, comments_enabled, downloadable.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/soundcloud/update_track \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"track_id":"track_8c41d2","fields":"fields"}'
Python
result = client.call("soundcloud", "update_track", {"track_id":"track_8c41d2","fields":"fields"})
Node.js
const result = await cotlet.call('soundcloud', 'update_track', {"track_id":"track_8c41d2","fields":"fields"});
CLI
cotlet call soundcloud update_track --data '{"track_id":"track_8c41d2","fields":"fields"}'

Example response

{
  "track_id": "2148839017",
  "updated": [
    "title",
    "tags"
  ],
  "title": "Night Drive (Extended)",
  "tags": [
    "deep house",
    "night",
    "extended"
  ]
}

Schedule release

write Confirm

POST https://cotlet.dev/api/v1/soundcloud/schedule_release

Schedules a private track to go public at the time you give. At that time it is released and appears in followers' Feeds. Only Artist Pro creators can schedule, only single tracks, and only tracks that are private. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: schedule_release
NameTypeDescription
track_id required string Track ID from list_tracks.
release_at required datetime ISO 8601 with time zone.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/soundcloud/schedule_release \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"track_id":"2148839017","release_at":"2026-10-16T18:00:00+02:00"}'
Python
result = client.call("soundcloud", "schedule_release", {"track_id":"2148839017","release_at":"2026-10-16T18:00:00+02:00"})
Node.js
const result = await cotlet.call('soundcloud', 'schedule_release', {"track_id":"2148839017","release_at":"2026-10-16T18:00:00+02:00"});
CLI
cotlet call soundcloud schedule_release --data '{"track_id":"2148839017","release_at":"2026-10-16T18:00:00+02:00"}'

Example response

{
  "track_id": "2148839017",
  "title": "Night Drive",
  "privacy": "scheduled",
  "status": "scheduled",
  "release_at": "2026-10-16T18:00:00+02:00",
  "url": "https://soundcloud.com/yourname/night-drive"
}

Set track privacy

write Confirm

POST https://cotlet.dev/api/v1/soundcloud/set_track_privacy

Makes a track public, so followers and search can see it, or private, so only people with its secret link can. Going public from private is a first release and reaches followers' Feeds. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: set_track_privacy
NameTypeDescription
track_id required string Track ID from list_tracks.
privacy required enum public or private.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/soundcloud/set_track_privacy \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"track_id":"track_8c41d2","privacy":"public"}'
Python
result = client.call("soundcloud", "set_track_privacy", {"track_id":"track_8c41d2","privacy":"public"})
Node.js
const result = await cotlet.call('soundcloud', 'set_track_privacy', {"track_id":"track_8c41d2","privacy":"public"});
CLI
cotlet call soundcloud set_track_privacy --data '{"track_id":"track_8c41d2","privacy":"public"}'

Example response

{
  "track_id": "2148839017",
  "privacy": "private",
  "secret_url": "https://soundcloud.com/yourname/night-drive/s-Ab12Cd34Ef"
}

Create playlist

write

POST https://cotlet.dev/api/v1/soundcloud/create_playlist

Creates a playlist from your tracks in the order you give. It is private by default and the response includes its secret link; anyone with that link can listen. Private tracks in a public playlist are not visible to listeners. create_playlist reaches no one until you share the link and is undone by deleting the playlist in SoundCloud, so it runs without asking first.

Parameters

Parameters: create_playlist
NameTypeDescription
title required string Playlist title.
track_ids required string[] Track IDs in play order.
description string Playlist description.
privacy enum private or public. Default: private.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/soundcloud/create_playlist \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"title","track_ids":["track ids"]}'
Python
result = client.call("soundcloud", "create_playlist", {"title":"title","track_ids":["track ids"]})
Node.js
const result = await cotlet.call('soundcloud', 'create_playlist', {"title":"title","track_ids":["track ids"]});
CLI
cotlet call soundcloud create_playlist --data '{"title":"title","track_ids":["track ids"]}'

Example response

{
  "playlist_id": "1877340021",
  "title": "Demos for Jan",
  "privacy": "private",
  "track_count": 3,
  "secret_url": "https://soundcloud.com/yourname/sets/demos-for-jan/s-Qw98Er76Ty"
}

Reply to comment

write Confirm

POST https://cotlet.dev/api/v1/soundcloud/reply_to_comment

Posts a reply under a comment on one of your tracks. The reply appears under your name. SoundCloud may block commenting for a while if many similar messages go out quickly. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: reply_to_comment
NameTypeDescription
comment_id required string Comment ID from list_comments.
body required string Reply text.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/soundcloud/reply_to_comment \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"comment_id":"3347102215","body":"Thank you! The bass line came together at 3 a.m."}'
Python
result = client.call("soundcloud", "reply_to_comment", {"comment_id":"3347102215","body":"Thank you! The bass line came together at 3 a.m."})
Node.js
const result = await cotlet.call('soundcloud', 'reply_to_comment', {"comment_id":"3347102215","body":"Thank you! The bass line came together at 3 a.m."});
CLI
cotlet call soundcloud reply_to_comment --data '{"comment_id":"3347102215","body":"Thank you! The bass line came together at 3 a.m."}'

Example response

{
  "comment_id": "3347102560",
  "reply_to": "3347102215",
  "status": "published"
}

Delete comment

write Confirm

POST https://cotlet.dev/api/v1/soundcloud/delete_comment

Removes a comment from one of your tracks. Deleted comments cannot be restored. With report_spam the comment is also reported for review by SoundCloud. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: delete_comment
NameTypeDescription
comment_id required string Comment ID from list_comments.
report_spam boolean Also report it as spam. Default: false.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/soundcloud/delete_comment \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"comment_id":"comment_8c41d2"}'
Python
result = client.call("soundcloud", "delete_comment", {"comment_id":"comment_8c41d2"})
Node.js
const result = await cotlet.call('soundcloud', 'delete_comment', {"comment_id":"comment_8c41d2"});
CLI
cotlet call soundcloud delete_comment --data '{"comment_id":"comment_8c41d2"}'

Example response

{
  "comment_id": "3347102498",
  "status": "deleted",
  "reported_as_spam": true
}

Send message

write Confirm

POST https://cotlet.dev/api/v1/soundcloud/send_message

Sends a direct message to one SoundCloud user, or into an existing conversation, under your name. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: send_message
NameTypeDescription
to required string Profile URL or conversation ID from list_conversations.
body required string Message text.
track_id string Attach one of your tracks.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/soundcloud/send_message \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"to","body":"body"}'
Python
result = client.call("soundcloud", "send_message", {"to":"to","body":"body"})
Node.js
const result = await cotlet.call('soundcloud', 'send_message', {"to":"to","body":"body"});
CLI
cotlet call soundcloud send_message --data '{"to":"to","body":"body"}'

Example response

{
  "conversation_id": "cv_5521",
  "message_id": "msg_88410",
  "status": "sent",
  "sent_at": "2026-10-11T09:05:00+02:00"
}