# Bandsintown API

> Every Bandsintown endpoint on Cotlet: inputs, JSON Schema, cURL, Python and Node.js examples and an example response for each call.

Source: https://cotlet.dev/docs/api/bandsintown

Docs sections: [Get started](https://cotlet.dev/docs.md) · [REST API](https://cotlet.dev/docs/api.md) · [MCP](https://cotlet.dev/docs/mcp.md) · [SDKs & CLI](https://cotlet.dev/docs/sdks.md) · [Integrations](https://cotlet.dev/docs/integrations.md)

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: https://cotlet.dev/integrations/bandsintown-api-mcp-server

## 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

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

Access: read.

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

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

### Request

**cURL**

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

**Python**

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

**Node.js**

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

**CLI**

```bash
cotlet call bandsintown list_events
```

### Example response

```json
{
  "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

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

Access: read.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `event_id` | string | yes | Event ID from list_events. |

### Request

**cURL**

```bash
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"}'
```

**Python**

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

**Node.js**

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

**CLI**

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

### Example response

```json
{
  "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

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

Access: read.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Venue name. |
| `city` | string | no | City, to narrow the results. |

### Request

**cURL**

```bash
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"}'
```

**Python**

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

**Node.js**

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

**CLI**

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

### Example response

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

## Get event stats

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

Access: read.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `artist_id` | string | no | Artist page you manage. Default: your first artist. |
| `event_id` | string | no | Only this event. Default: all upcoming events. |

### Request

**cURL**

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

**Python**

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

**Node.js**

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

**CLI**

```bash
cotlet call bandsintown get_event_stats
```

### Example response

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

## Get follower stats

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

Access: read.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `artist_id` | string | no | Artist page you manage. Default: your first artist. |
| `period` | enum | no | 7d, 4w or 12m. Default: 4w. |

### Request

**cURL**

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

**Python**

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

**Node.js**

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

**CLI**

```bash
cotlet call bandsintown get_follower_stats
```

### Example response

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

## Get top markets

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

Access: read.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `artist_id` | string | no | Artist page you manage. Default: your first artist. |
| `rank_by` | enum | no | trackers or fan_requests. Default: trackers. |
| `limit` | integer | no | 1 to 50. Default: 10. |

### Request

**cURL**

```bash
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}'
```

**Python**

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

**Node.js**

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

**CLI**

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

### Example response

```json
{
  "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

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

Access: write.

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

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

### Request

**cURL**

```bash
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"}]}'
```

**Python**

```python
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"}]})
```

**Node.js**

```js
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"}]});
```

**CLI**

```bash
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

```json
{
  "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

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

Access: write. Confirm: waits for the user's OK before it runs.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `event_id` | string | yes | Event ID from list_events. |
| `fields` | object | yes | Any of starts_at, venue_id, custom_location, title, description, lineup, ticket_links. |
| `notify_followers` | boolean | no | Alert followers about the change. Default: false. |

### Request

**cURL**

```bash
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}'
```

**Python**

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

**Node.js**

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

**CLI**

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

### Example response

```json
{
  "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

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

Access: write. Confirm: waits for the user's OK before it runs.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `event_id` | string | yes | Event ID from list_events. |
| `publish_at` | datetime | no | Schedule for later. Default: now. |
| `notify_followers` | boolean | no | Alert followers. Default: true. |

### Request

**cURL**

```bash
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"}'
```

**Python**

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

**Node.js**

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

**CLI**

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

### Example response

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

## Delete event

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

Access: write. Confirm: waits for the user's OK before it runs.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `event_id` | string | yes | Event ID from list_events. |

### Request

**cURL**

```bash
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"}'
```

**Python**

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

**Node.js**

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

**CLI**

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

### Example response

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

## Send fan message

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

Access: write. Confirm: waits for the user's OK before it runs.

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

| Name | Type | Required | Description |
|---|---|---|---|
| `artist_id` | string | no | Artist page you manage. Default: your first artist. |
| `body` | string | yes | Post text. Include your Smart Link. |
| `send_at` | datetime | no | Schedule for later. Default: now. |

### Request

**cURL**

```bash
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"}'
```

**Python**

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

**Node.js**

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

**CLI**

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

### Example response

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