> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recoupable.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Artist Events

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



## OpenAPI

````yaml api-reference/openapi/research.json POST /api/research/events
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
security: []
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 `checkoutUrl` to
            top up.
          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 and auto-recharge
        did not cover the call.
      properties:
        error:
          type: string
          enum:
            - insufficient_credits
        remaining_credits:
          type: integer
          example: 0
        required_credits:
          type: integer
          example: 5
        checkoutUrl:
          type: string
          description: Stripe checkout link to top up credits.
        declineReason:
          type: string
          description: Card decline reason when auto-recharge was attempted and failed.
      required:
        - error
        - remaining_credits
        - required_credits
        - checkoutUrl

````