# Artist Events

Source: https://recoupable.dev/docs/api-reference/research/events

List an artist's live shows. Returns one row per event with venue, city, country, ticket link, and lineup.

## POST /api/research/events

Full OpenAPI specification: https://recoupable.dev/docs/spec/research.json

## Authentication

The supplied specification does not declare an OpenAPI security object for this operation. Its declared headers and parameters still apply. Consult the authentication guide and the full specification before calling it.

[Authentication guide](https://recoupable.dev/docs/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Recoup API - Research",
    "description": "API documentation for the Recoup platform - an AI agent platform for the music industry",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.recoupable.dev"
    }
  ],
  "paths": {
    "/api/research/events": {
      "post": {
        "description": "List an artist's live shows. Returns one row per event with venue, city, country, ticket link, and lineup.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResearchEventsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Events for the artist. An artist with no matching events returns an empty `events` array, not an error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResearchEventsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResearchErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed — invalid or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResearchErrorResponse"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient research credits — the body includes a static `billingUrl`. No Stripe object is created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResearchInsufficientCreditsResponse"
                }
              }
            }
          },
          "404": {
            "description": "The artist has no live-events profile connected, so no events can be looked up. Distinct from a 200 with an empty `events` array, which means the artist is connected but has no matching events.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResearchErrorResponse"
                },
                "example": {
                  "status": "error",
                  "error": "Error: no bandsintown ID connected to this artist. Please connect the bandsintown ID in this format: bandsintown.com/a/{id}-{slug} Docs here: https://docs.recoupable.dev/api-reference/artists/update#body-profile-urls"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ResearchEventsRequest": {
        "type": "object",
        "required": [
          "artist_id"
        ],
        "description": "Request body for artist event lookup.",
        "properties": {
          "artist_id": {
            "type": "string",
            "format": "uuid",
            "description": "Recoup artist id. Events are resolved through the live-events profile connected to this artist, so the lookup is exact and cannot drift to a same-named performer. Returns 404 if no live-events profile is connected.",
            "example": "123694f2-1dab-40b4-8a75-84d39571c0bc"
          },
          "date": {
            "type": "string",
            "enum": [
              "upcoming",
              "past",
              "all"
            ],
            "default": "upcoming",
            "description": "Which events to return."
          }
        }
      },
      "ResearchEventsResponse": {
        "type": "object",
        "required": [
          "status",
          "events"
        ],
        "description": "Live events for one artist.",
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "events": {
            "type": "array",
            "description": "Matching events, ascending by date. Empty when the artist has none.",
            "items": {
              "type": "object",
              "properties": {
                "date": {
                  "type": "string",
                  "description": "Event date as ISO 8601 (YYYY-MM-DD).",
                  "example": "2026-09-26"
                },
                "venue": {
                  "type": "string",
                  "description": "Venue name.",
                  "example": "O2 Academy Brixton"
                },
                "city": {
                  "type": "string",
                  "example": "London"
                },
                "region": {
                  "type": "string",
                  "nullable": true,
                  "description": "State or region where the source provides one. US venues carry a state code such as \"TN\"; most non-US venues return an empty string, as in the example below.",
                  "example": ""
                },
                "country": {
                  "type": "string",
                  "description": "Country name. Pair with `city` before filtering by market, since city names such as London and Paris are not unique across countries.",
                  "example": "United Kingdom"
                },
                "ticket_url": {
                  "type": "string",
                  "nullable": true,
                  "description": "Ticket link where one is published."
                },
                "sold_out": {
                  "type": "boolean",
                  "description": "Whether the source marks the event sold out."
                },
                "lineup": {
                  "type": "array",
                  "description": "Billed artists, the queried artist first. More than one entry means a shared bill.",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "ResearchErrorResponse": {
        "type": "object",
        "required": [
          "status",
          "error"
        ],
        "description": "Error response returned by all research endpoints for validation failures (400) and authentication errors (401).",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ],
            "example": "error"
          },
          "error": {
            "type": "string",
            "description": "Human-readable error message describing what went wrong.",
            "example": "Missing required parameter: artist"
          }
        }
      },
      "ResearchInsufficientCreditsResponse": {
        "type": "object",
        "description": "Returned (402) when the account lacks research credits. Nothing is charged and no Stripe object is created. Credits must be bought explicitly via [`POST /api/credits/sessions`](/api-reference/credits/sessions-create).",
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "insufficient_credits"
            ]
          },
          "remaining_credits": {
            "type": "integer",
            "example": 0
          },
          "required_credits": {
            "type": "integer",
            "example": 5
          },
          "billingUrl": {
            "type": "string",
            "description": "Static link to the Recoup app, where a human can save a card and buy credits. It is a constant, not a freshly minted Stripe Checkout Session, so a credit-gated endpoint that keeps returning 402 creates nothing. To buy credits programmatically, call [`POST /api/credits/sessions`](/api-reference/credits/sessions-create).",
            "example": "https://app.recoupable.dev"
          }
        },
        "required": [
          "error",
          "remaining_credits",
          "required_credits",
          "billingUrl"
        ]
      }
    }
  }
}
```