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

> ## Agent Instructions
> Base URL: https://api.eventory.ai. Send your API key in the apikey header. Market Data and Live Availability calls cost credits, pings included; GET /usage is free, so use it to test a key. Costs per endpoint: https://eventory.ai/docs/credits-and-access.md

# List watchlist items

> Returns the watchlist items owned by your account, newest first. `items` is an
empty array if you have none.

Omitting `limit` returns the entire watchlist in one response. Large watchlists
are easier to handle page by page: pass `limit` and walk `offset` forward until
`has_more` is `false`.

Ordering is stable across pages — creation time descending, then `id`
descending — so paging never repeats or skips an item, even when many items
share a creation timestamp because they were added in bulk.

**Cost:** free.




## OpenAPI

````yaml /openapi.yaml get /watchlist
openapi: 3.1.0
info:
  title: Eventory API
  version: '1.0'
  description: >
    Every HTTP endpoint of the Eventory platform, reached through the single
    public

    gateway at `https://api.eventory.ai`. The Notifications API is a

    WebSocket and is documented separately under **Notifications API**.


    Authenticate every request with the `apikey` header. Each endpoint lists its

    credit cost; see **Credits & access** for how billing works.
  contact:
    name: Eventory
    url: https://eventory.ai
servers:
  - url: https://api.eventory.ai
    description: Production
security:
  - apiKey: []
tags:
  - name: Market Data
    description: |
      Historical and aggregated marketplace data for events and artists, plus
      full-text search over the Eventory catalog. Polling API.
      **1 credit per request** (sales list scales with rows requested).
  - name: Live Availability
    description: >
      On-demand scrape of the current ticket availability for one event on one
      of

      the twelve supported platforms. **5 credits per request.**
  - name: Watchlist
    description: |
      Manage the events your account monitors. The watchlist drives the
      Notifications API. **Free.**
  - name: Account
    description: Your plan and credit usage, live from billing. **Free.**
paths:
  /watchlist:
    get:
      tags:
        - Watchlist
      summary: List watchlist items
      description: >
        Returns the watchlist items owned by your account, newest first. `items`
        is an

        empty array if you have none.


        Omitting `limit` returns the entire watchlist in one response. Large
        watchlists

        are easier to handle page by page: pass `limit` and walk `offset`
        forward until

        `has_more` is `false`.


        Ordering is stable across pages — creation time descending, then `id`

        descending — so paging never repeats or skips an item, even when many
        items

        share a creation timestamp because they were added in bulk.


        **Cost:** free.
      operationId: listWatchlist
      parameters:
        - name: limit
          in: query
          required: false
          description: >
            Maximum number of items to return. Omit to return the entire
            watchlist.

            A value outside `1..1000` is rejected with `400`.
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            example: 500
        - name: offset
          in: query
          required: false
          description: |
            Number of items to skip before collecting the page. Defaults to 0.
            Items are ordered by creation time, newest first.
          schema:
            type: integer
            minimum: 0
            default: 0
            example: 1000
      responses:
        '200':
          description: >-
            One page of watchlist items, with the totals needed to page through
            the rest.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistPage'
        '400':
          description: '`limit` or `offset` is not an integer, or is out of range.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistError'
              examples:
                limit:
                  value:
                    error: '"limit" must be an integer between 1 and 1000'
                offset:
                  value:
                    error: '"offset" must be an integer >= 0'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    WatchlistPage:
      type: object
      required:
        - items
        - total
        - offset
        - limit
        - has_more
      properties:
        items:
          type: array
          description: This page of watchlist items, newest first.
          items:
            $ref: '#/components/schemas/WatchlistItem'
        total:
          type: integer
          description: Total items on the account, independent of `limit` and `offset`.
          example: 6788
        offset:
          type: integer
          description: The offset that was applied.
          example: 1000
        limit:
          type:
            - integer
            - 'null'
          description: The limit that was applied; `null` when none was passed.
          example: 1000
        has_more:
          type: boolean
          description: '`true` when items remain after this page.'
          example: true
    WatchlistError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
    WatchlistItem:
      allOf:
        - type: object
          required:
            - id
            - client_id
            - created_at
            - updated_at
            - deleted
          properties:
            id:
              type: integer
              description: Assigned on create. Use it in the URL path.
            client_id:
              type: integer
              description: The account that owns this item.
            created_at:
              type: string
              description: >-
                Timestamp without a UTC offset, e.g.
                `2026-06-18T09:20:00.123456`.
            updated_at:
              type: string
              description: >-
                Timestamp without a UTC offset, e.g.
                `2026-06-18T09:20:00.123456`.
            deleted:
              type: boolean
              description: >-
                Legacy field, always `false`. `DELETE` removes the item
                permanently.
        - $ref: '#/components/schemas/WatchlistIdentity'
        - $ref: '#/components/schemas/WatchlistFilters'
      example:
        id: 123
        client_id: 42
        website: ticketmaster
        event: 0200642CF18CAA24
        region: US
        min_price_filter: null
        max_price_filter: 250
        min_avg_price_threshold: null
        max_avg_price_threshold: null
        stock_threshold_filter: 1
        stock_threshold_filter_max: null
        min_stock_increase_filter: 4
        min_stock_decrease_filter: null
        seat_quantity: 2
        priority: 0
        section: null
        keywords: null
        date_filter: null
        row_filter: null
        change_type: stock_increase
        standard_tickets: true
        resale_tickets: false
        general_admission_tickets: false
        platinum_tickets: false
        vip_tickets: false
        no_restricted_view: false
        no_accessibility: false
        no_presale: false
        auto_add_to_watchlist: false
        task_active: true
        muted_until: null
        notes: null
        tm_did: null
        roles_json: null
        webhook_setting_id: null
        role_id: null
        website_id: null
        created_at: '2026-06-18T09:20:00.123456'
        updated_at: '2026-06-18T09:20:00.123456'
        deleted: false
    GatewayError:
      type: object
      description: >
        Envelope for every failure decided by the gateway (auth, ACL, billing,

        rate limit, unknown route, upstream 5xx). Key on `code`; `message` is
        prose

        and may change.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - unauthenticated
                - invalid_credentials
                - forbidden
                - no_subscription
                - limit_reached
                - no_billing_account
                - plan_unavailable
                - payment_required
                - invalid_parameter
                - rate_limited
                - not_found
                - service_unavailable
            message:
              type: string
    WatchlistIdentity:
      type: object
      required:
        - website
        - event
        - region
      properties:
        website:
          type: string
          description: >
            Platform to monitor, e.g. `ticketmaster`. An unknown value is
            rejected with

            `400` (`Unknown website: "<website>". …`). For the platforms with a
            known id

            format, `event` is checked against that platform's (and often that
            region's)

            format. Some platforms are available on request: until one is
            enabled for

            your account, using it returns `403`

            (`Website "<website>" is not available on this account`). See

            [Watchlist platforms](/guides/watchlist-platforms) for the
            recognised keys,

            the retired aliases, and the discovery monitors.
          example: ticketmaster
        event:
          type: string
          description: >
            Event identifier on that platform — a bare id or a full event URL
            depending

            on the platform. On create, several ids may be sent comma-separated
            to make

            one item each. For a discovery monitor this is the artist or venue
            URL

            rather than an event id.
          example: 0200642CF18CAA24
        region:
          type: string
          description: Region or market, e.g. `US`.
          example: US
    WatchlistFilters:
      type: object
      description: >
        Optional filters and options. Omit a field to keep the server default.

        Boolean fields and `priority` are never `null`; sending `null` for one
        is ignored.
      properties:
        min_price_filter:
          type:
            - number
            - 'null'
          description: Ignore tickets priced below this.
        max_price_filter:
          type:
            - number
            - 'null'
          description: Ignore tickets priced above this.
        min_avg_price_threshold:
          type:
            - number
            - 'null'
        max_avg_price_threshold:
          type:
            - number
            - 'null'
        stock_threshold_filter:
          type:
            - integer
            - 'null'
          description: Minimum available stock to notify on.
        stock_threshold_filter_max:
          type:
            - integer
            - 'null'
          description: Maximum available stock to notify on.
        min_stock_increase_filter:
          type:
            - integer
            - 'null'
          description: >
            Only notify when the stock increase is at least this many tickets.

            Must be a positive integer; `null` turns the filter off. `0` or a
            negative

            value is rejected with `400`.
          example: 4
        min_stock_decrease_filter:
          type:
            - integer
            - 'null'
          description: >
            Only notify when the stock decrease is at least this many tickets.

            Must be a positive integer; `null` turns the filter off. `0` or a
            negative

            value is rejected with `400`.
          example: 4
        vip_tickets:
          type: boolean
          description: Include VIP tickets.
        seat_quantity:
          type:
            - integer
            - 'null'
          description: Number of contiguous seats wanted.
        priority:
          type:
            - integer
            - 'null'
        section:
          type:
            - string
            - 'null'
          description: Restrict to a section name.
        keywords:
          type:
            - string
            - 'null'
        date_filter:
          type:
            - string
            - 'null'
        row_filter:
          type:
            - string
            - 'null'
        change_type:
          type:
            - string
            - 'null'
          description: >
            Which change triggers a notification. The stream enforces this
            server-side.

            Any value outside this list is rejected with `400`.
          enum:
            - stock_increase
            - stock_decrease
            - price_decrease
            - price_increase
            - null
          default: stock_increase
        standard_tickets:
          type: boolean
        resale_tickets:
          type: boolean
        general_admission_tickets:
          type: boolean
        platinum_tickets:
          type: boolean
        no_restricted_view:
          type: boolean
        no_accessibility:
          type: boolean
        no_presale:
          type: boolean
        auto_add_to_watchlist:
          type: boolean
        task_active:
          type: boolean
          description: Whether monitoring for this item is active.
        muted_until:
          type:
            - string
            - 'null'
          format: date-time
          description: Suppress notifications until this time.
        notes:
          type:
            - string
            - 'null'
        tm_did:
          type:
            - string
            - 'null'
          description: Ticketmaster device id.
        roles_json:
          description: Pass-through JSON; treat as opaque.
          oneOf:
            - type: object
              additionalProperties: true
            - type: array
              items: {}
            - type: 'null'
        webhook_setting_id:
          type:
            - integer
            - 'null'
        role_id:
          type:
            - integer
            - 'null'
        website_id:
          type:
            - integer
            - 'null'
          readOnly: true
          description: Read-only. Accepted and ignored on write.
  responses:
    Unauthenticated:
      description: No credential was sent, or the key was rejected.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GatewayError'
          examples:
            missing:
              value:
                error:
                  code: unauthenticated
                  message: Authentication is required to access this resource.
            invalid:
              value:
                error:
                  code: invalid_credentials
                  message: Your credentials are invalid or expired.
    Forbidden:
      description: >-
        The key is valid but not granted this route. Contact support to enable
        it.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GatewayError'
          example:
            error:
              code: forbidden
              message: You do not have access to this service.
    ServiceUnavailable:
      description: The upstream service failed or is unreachable. Retry with backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GatewayError'
          example:
            error:
              code: service_unavailable
              message: The service is temporarily unavailable.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: apikey
      description: Your Eventory API key. Sent as the `apikey` request header.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.