API REFERENCE

Artist Events

On this page

POST/api/research/events

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

Authentication

See the authentication guide for API key and account access requirements.

Request

cURL

curl --request POST \
  --url 'https://api.recoupable.dev/api/research/events' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "artist_id": "123694f2-1dab-40b4-8a75-84d39571c0bc"
}'

Request body required

application/json

artist_idstringrequired

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.

format: uuid

datestring · enum

Which events to return.

Values: "upcoming", "past", "all"

Default: "upcoming"

Responses

200Events for the artist. An artist with no matching events returns an empty events array, not an error.

application/json

statusstringrequired

eventsarray<object>required

Matching events, ascending by date. Empty when the artist has none.

Item properties

datestring

Event date as ISO 8601 (YYYY-MM-DD).

venuestring

Venue name.

citystring

regionstringnullable

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.

countrystring

Country name. Pair with city before filtering by market, since city names such as London and Paris are not unique across countries.

ticket_urlstringnullable

Ticket link where one is published.

sold_outboolean

Whether the source marks the event sold out.

lineuparray<string>

Billed artists, the queried artist first. More than one entry means a shared bill.

Item properties

string

400Validation error

application/json

statusstring · enumrequired

Values: "error"

errorstringrequired

Human-readable error message describing what went wrong.

401Authentication failed — invalid or missing API key

application/json

statusstring · enumrequired

Values: "error"

errorstringrequired

Human-readable error message describing what went wrong.

402Insufficient research credits — the body includes a static billingUrl. No Stripe object is created.

application/json

errorstring · enumrequired

Values: "insufficient_credits"

remaining_creditsintegerrequired

required_creditsintegerrequired

billingUrlstringrequired

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.

404The 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.

application/json

statusstring · enumrequired

Values: "error"

errorstringrequired

Human-readable error message describing what went wrong.

404 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"
}

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download research.json

View operation source

json

{
  "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"
          }
        }
      }
    }
  }
}