REST API reference

Bandsintown API

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

Base URL: https://cotlet.dev/api/v1/bandsintown
Connects with: Your own Bandsintown for Artists account, with admin access to the artist page
Integration page: Bandsintown

Bandsintown Endpoints
Endpoint	Access	Description
list_events	read	Events on your artist page with date, venue, ticket links and status.
get_event	read	One event in full: venue, lineup, description, ticket links, on-sale time and URL.
search_venues	read	Find a Bandsintown venue by name and city, to attach it to an event.
get_event_stats	read	RSVPs for each of your shows, as in the Events Performance view of Insights.
get_follower_stats	read	Total followers, RSVPs and ticket clicks with the change over a period, from Insights.
get_top_markets	read	Locations where your fans are, ranked by trackers or fan requests.
create_event	write	New event saved as a draft. Nothing is public until you publish it.
update_event	write	Change the date, venue, lineup, description or ticket links of a draft or published event.
publish_event	write	Publish a draft now or at a set time, optionally notifying followers.
delete_event	write	Remove an event from your artist page.
send_fan_message	write	Post to your followers by push notification and email, now or at a set time.

List events

read

POST https://cotlet.dev/api/v1/bandsintown/list_events

Returns events of one artist page, soonest first, with date, venue, ticket links and whether each is published or a draft. Filter by status or by date range. Use the event_id from each item in the other tools.

Parameters

Parameters: list_events
Name	Type	Description
artist_id	string	Artist page you manage. Default: your first artist.
status	enum	upcoming, past, draft or all. Default: upcoming.
from	date	Only events on or after this date.
to	date	Only events on or before this date.

Request

cURL Python Node.js CLI

curl -X POST https://cotlet.dev/api/v1/bandsintown/list_events \
  -H "Authorization: Bearer $COTLET_API_KEY"

result = client.call("bandsintown", "list_events")

const result = await cotlet.call('bandsintown', 'list_events');

cotlet call bandsintown list_events

Example response

{
  "events": [
    {
      "event_id": "1037728455",
      "status": "published",
      "starts_at": "2026-11-14T20:00:00+00:00",
      "venue": {
        "name": "Brudenell Social Club",
        "city": "Leeds",
        "country": "United Kingdom"
      },
      "ticket_links": [
        {
          "url": "https://tickets.example.com/yourband-leeds",
          "type": "tickets"
        }
      ],
      "url": "https://www.bandsintown.com/e/1037728455"
    },
    {
      "event_id": "1037728501",
      "status": "draft",
      "starts_at": "2026-12-03T19:30:00+01:00",
      "venue": {
        "name": "Columbiahalle",
        "city": "Berlin",
        "country": "Germany"
      },
      "ticket_links": [],
      "url": null
    }
  ]
}

Get event

read

POST https://cotlet.dev/api/v1/bandsintown/get_event

Returns one event with every field you can set in the event form: location, lineup, description and ticket links with their on-sale time. Bandsintown rewrites ticket links, so the links shown are the ones you entered.

Parameters

Parameters: get_event
Name	Type	Description
event_id required	string	Event ID from list_events.

Request

cURL Python Node.js CLI

curl -X POST https://cotlet.dev/api/v1/bandsintown/get_event \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"event_8c41d2"}'

result = client.call("bandsintown", "get_event", {"event_id":"event_8c41d2"})

const result = await cotlet.call('bandsintown', 'get_event', {"event_id":"event_8c41d2"});

cotlet call bandsintown get_event --data '{"event_id":"event_8c41d2"}'

Example response

{
  "event_id": "1037728455",
  "status": "published",
  "starts_at": "2026-11-14T20:00:00+00:00",
  "venue": {
    "name": "Brudenell Social Club",
    "city": "Leeds",
    "country": "United Kingdom"
  },
  "lineup": [
    "Your Band"
  ],
  "description": "Album launch show.",
  "ticket_links": [
    {
      "url": "https://tickets.example.com/yourband-leeds",
      "type": "tickets",
      "on_sale_at": "2026-10-16T10:00:00+01:00"
    }
  ],
  "url": "https://www.bandsintown.com/e/1037728455"
}

Search venues

read

POST https://cotlet.dev/api/v1/bandsintown/search_venues

Searches the Bandsintown venue list and returns matches with a venue_id. If the venue is not listed, pass custom_location to create_event instead. Attach a venue with a full location: events without one are not considered by Bandsintown's recommendations.

Parameters

Parameters: search_venues
Name	Type	Description
query required	string	Venue name.
city	string	City, to narrow the results.

Request

cURL Python Node.js CLI

curl -X POST https://cotlet.dev/api/v1/bandsintown/search_venues \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"query"}'

result = client.call("bandsintown", "search_venues", {"query":"query"})

const result = await cotlet.call('bandsintown', 'search_venues', {"query":"query"});

cotlet call bandsintown search_venues --data '{"query":"query"}'

Example response

{
  "venues": [
    {
      "venue_id": "v_118302",
      "name": "Brudenell Social Club",
      "city": "Leeds",
      "country": "United Kingdom"
    }
  ]
}

Get event stats

read

POST https://cotlet.dev/api/v1/bandsintown/get_event_stats

Returns RSVPs per show from Insights, the same figures as Events Performance. Pass event_id for one show, or leave it out for all upcoming shows.

Parameters

Parameters: get_event_stats
Name	Type	Description
artist_id	string	Artist page you manage. Default: your first artist.
event_id	string	Only this event. Default: all upcoming events.

Request

cURL Python Node.js CLI

curl -X POST https://cotlet.dev/api/v1/bandsintown/get_event_stats \
  -H "Authorization: Bearer $COTLET_API_KEY"

result = client.call("bandsintown", "get_event_stats")

const result = await cotlet.call('bandsintown', 'get_event_stats');

cotlet call bandsintown get_event_stats

Example response

{
  "events": [
    {
      "event_id": "1037728455",
      "venue": "Brudenell Social Club",
      "starts_at": "2026-11-14T20:00:00+00:00",
      "rsvps": 212
    }
  ]
}

Get follower stats

read

POST https://cotlet.dev/api/v1/bandsintown/get_follower_stats

Returns the Insights summary: total followers, RSVPs and ticket clicks, with how much each changed in the period. Periods match the Insights filters. Read only.

Parameters

Parameters: get_follower_stats
Name	Type	Description
artist_id	string	Artist page you manage. Default: your first artist.
period	enum	7d, 4w or 12m. Default: 4w.

Request

cURL Python Node.js CLI

curl -X POST https://cotlet.dev/api/v1/bandsintown/get_follower_stats \
  -H "Authorization: Bearer $COTLET_API_KEY"

result = client.call("bandsintown", "get_follower_stats")

const result = await cotlet.call('bandsintown', 'get_follower_stats');

cotlet call bandsintown get_follower_stats

Example response

{
  "period": "7d",
  "followers": {
    "total": 18420,
    "change": 163
  },
  "rsvps": {
    "total": 2310,
    "change": 54
  },
  "ticket_clicks": {
    "total": 1190,
    "change": 37
  }
}

Get top markets

read

POST https://cotlet.dev/api/v1/bandsintown/get_top_markets

Returns your top locations from Insights, the same list as Top Markets. Sort by trackers (followers) or by fan requests (fans asking you to play there). Read only.

Parameters

Parameters: get_top_markets
Name	Type	Description
artist_id	string	Artist page you manage. Default: your first artist.
rank_by	enum	trackers or fan_requests. Default: trackers.
limit	integer	1 to 50. Default: 10.

Request

cURL Python Node.js CLI

curl -X POST https://cotlet.dev/api/v1/bandsintown/get_top_markets \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rank_by":"fan_requests","limit":25}'

result = client.call("bandsintown", "get_top_markets", {"rank_by":"fan_requests","limit":25})

const result = await cotlet.call('bandsintown', 'get_top_markets', {"rank_by":"fan_requests","limit":25});

cotlet call bandsintown get_top_markets --data '{"rank_by":"fan_requests","limit":25}'

Example response

{
  "markets": [
    {
      "rank": 1,
      "location": "London, United Kingdom",
      "trackers": 2104,
      "fan_requests": 311
    },
    {
      "rank": 2,
      "location": "Leeds, United Kingdom",
      "trackers": 1388,
      "fan_requests": 96
    }
  ]
}

Create event

write

POST https://cotlet.dev/api/v1/bandsintown/create_event

Saves a new event as a draft; Bandsintown lists drafts under Drafts. Attach a venue from search_venues or pass custom_location. One ticket link must carry the Tickets label. create_event reaches no one and one delete_event call undoes it, so it runs without asking first.

Parameters

Parameters: create_event
Name	Type	Description
artist_id	string	Artist page you manage. Default: your first artist.
starts_at required	datetime	Local venue time, ISO 8601.
venue_id	string	Venue from search_venues. Or use custom_location.
custom_location	object	name, city, country, for a place not in the venue list.
title	string	Event name, if different from the artist name.
description	string	Event description.
lineup	string[]	Other artists with a Bandsintown page on the bill.
ticket_links	object[]	List of { url, type, on_sale_at }; type is tickets, free or sold_out. One link must be tickets.

Request

cURL Python Node.js CLI

curl -X POST https://cotlet.dev/api/v1/bandsintown/create_event \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"starts_at":"2026-11-14T20:00:00+00:00","venue_id":"v_118302","ticket_links":[{"url":"https://tickets.example.com/yourband-leeds","type":"tickets"}]}'

result = client.call("bandsintown", "create_event", {"starts_at":"2026-11-14T20:00:00+00:00","venue_id":"v_118302","ticket_links":[{"url":"https://tickets.example.com/yourband-leeds","type":"tickets"}]})

const result = await cotlet.call('bandsintown', 'create_event', {"starts_at":"2026-11-14T20:00:00+00:00","venue_id":"v_118302","ticket_links":[{"url":"https://tickets.example.com/yourband-leeds","type":"tickets"}]});

cotlet call bandsintown create_event --data '{"starts_at":"2026-11-14T20:00:00+00:00","venue_id":"v_118302","ticket_links":[{"url":"https://tickets.example.com/yourband-leeds","type":"tickets"}]}'

Example response

{
  "event_id": "1037728455",
  "status": "draft",
  "starts_at": "2026-11-14T20:00:00+00:00",
  "venue": {
    "name": "Brudenell Social Club",
    "city": "Leeds",
    "country": "United Kingdom"
  },
  "ticket_links": [
    {
      "url": "https://tickets.example.com/yourband-leeds",
      "type": "tickets"
    }
  ],
  "url": null
}

Update event

write Confirm

POST https://cotlet.dev/api/v1/bandsintown/update_event

Changes only the fields you pass, on a published event or a draft. Bandsintown notifies followers of changes unless Notify my Followers is off; notify_followers defaults to false here, so set it to true only for changes fans must hear about, such as a new venue. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: update_event
Name	Type	Description
event_id required	string	Event ID from list_events.
fields required	object	Any of starts_at, venue_id, custom_location, title, description, lineup, ticket_links.
notify_followers	boolean	Alert followers about the change. Default: false.

Request

cURL Python Node.js CLI

curl -X POST https://cotlet.dev/api/v1/bandsintown/update_event \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"1037728455","fields":{"starts_at":"2026-11-21T20:00:00+00:00"},"notify_followers":true}'

result = client.call("bandsintown", "update_event", {"event_id":"1037728455","fields":{"starts_at":"2026-11-21T20:00:00+00:00"},"notify_followers":True})

const result = await cotlet.call('bandsintown', 'update_event', {"event_id":"1037728455","fields":{"starts_at":"2026-11-21T20:00:00+00:00"},"notify_followers":true});

cotlet call bandsintown update_event --data '{"event_id":"1037728455","fields":{"starts_at":"2026-11-21T20:00:00+00:00"},"notify_followers":true}'

Example response

{
  "event_id": "1037728455",
  "status": "published",
  "starts_at": "2026-11-21T20:00:00+00:00",
  "ticket_links": [
    {
      "url": "https://tickets.example.com/yourband-leeds",
      "type": "tickets"
    }
  ],
  "followers_notified": false
}

Publish event

write Confirm

POST https://cotlet.dev/api/v1/bandsintown/publish_event

Publishes a draft now, or schedules it, as the dashboard's Publish and Schedule to Publish do. With notify_followers on, Bandsintown alerts followers. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: publish_event
Name	Type	Description
event_id required	string	Event ID from list_events.
publish_at	datetime	Schedule for later. Default: now.
notify_followers	boolean	Alert followers. Default: true.

Request

cURL Python Node.js CLI

curl -X POST https://cotlet.dev/api/v1/bandsintown/publish_event \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"event_8c41d2"}'

result = client.call("bandsintown", "publish_event", {"event_id":"event_8c41d2"})

const result = await cotlet.call('bandsintown', 'publish_event', {"event_id":"event_8c41d2"});

cotlet call bandsintown publish_event --data '{"event_id":"event_8c41d2"}'

Example response

{
  "event_id": "1037728501",
  "status": "scheduled",
  "publish_at": "2026-10-16T10:00:00+01:00",
  "followers_notified": true
}

Delete event

write Confirm

POST https://cotlet.dev/api/v1/bandsintown/delete_event

Deletes one event from your artist page, as the red X on the Events page does. It cannot be undone with a tool, so you re-create the event if needed. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: delete_event
Name	Type	Description
event_id required	string	Event ID from list_events.

Request

cURL Python Node.js CLI

curl -X POST https://cotlet.dev/api/v1/bandsintown/delete_event \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"event_8c41d2"}'

result = client.call("bandsintown", "delete_event", {"event_id":"event_8c41d2"})

const result = await cotlet.call('bandsintown', 'delete_event', {"event_id":"event_8c41d2"});

cotlet call bandsintown delete_event --data '{"event_id":"event_8c41d2"}'

Example response

{
  "event_id": "1037728501",
  "status": "deleted"
}

Send fan message

write Confirm

POST https://cotlet.dev/api/v1/bandsintown/send_fan_message

Sends a Bandsintown post to your followers: push notification to fans who have enabled it, and email. Send now or schedule with send_at. Add your Smart Link so fans can find your shows. Your latest non-targeted post shows at the top of your artist page. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: send_fan_message
Name	Type	Description
artist_id	string	Artist page you manage. Default: your first artist.
body required	string	Post text. Include your Smart Link.
send_at	datetime	Schedule for later. Default: now.

Request

cURL Python Node.js CLI

curl -X POST https://cotlet.dev/api/v1/bandsintown/send_fan_message \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body":"body"}'

result = client.call("bandsintown", "send_fan_message", {"body":"body"})

const result = await cotlet.call('bandsintown', 'send_fan_message', {"body":"body"});

cotlet call bandsintown send_fan_message --data '{"body":"body"}'

Example response

{
  "message_id": "msg_20418",
  "status": "scheduled",
  "send_at": "2026-10-16T10:00:00+01:00"
}

Parameters

Request

Example response

Parameters

Request

Example response

Parameters

Request

Example response

Parameters

Request

Example response

Parameters

Request

Example response

Parameters

Request

Example response

Parameters

Request

Example response

Parameters

Request

Example response

Parameters

Request

Example response

Parameters

Request

Example response

Parameters

Request

Example response

Analytics cookies