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

# List a user's matched events

> The user's attended-event history, newest first, with the matched media attached to
each event.

This is everything an events tab and an event detail screen need. The media for an
event is included here, so opening an event costs no extra request.

Hidden events, and events not licensed for redistribution, are filtered out and never
appear.




## OpenAPI

````yaml /api-reference/openapi.yaml get /users/{user_id}/events
openapi: 3.1.0
info:
  title: FanFeed Partner API
  version: 1.0.0
  description: >
    FanFeed turns a user's camera roll into an attended-event history. Your app
    sends photo

    *metadata*; FanFeed matches it against live-event data and returns the
    events those photos

    were taken at, along with the stats derived from that history.


    Five endpoints cover the whole integration:


    | Endpoint | Purpose |

    |---|---|

    | `POST /users` | Create a FanFeed user, once, when your user opts in |

    | `POST /users/{user_id}/media` | Send photo metadata in batches; get
    matched events back |

    | `POST /users/{user_id}/sync-complete` | Tell FanFeed a library scan
    finished |

    | `GET /users/{user_id}/events` | The user's matched event history |

    | `GET /users/{user_id}/stats` | Profile statistics |
  contact:
    name: FanFeed Engineering
    email: engineering@fanfeed.ai
servers:
  - url: https://api.fanfeed.ai/v1
    description: Production
  - url: https://api-dev.fanfeed.ai/v1
    description: Development
security:
  - PartnerApiKey: []
tags:
  - name: Users
    description: Creating a FanFeed user for one of your users.
  - name: Media
    description: Batch camera-roll metadata ingest and event matching.
  - name: Sync
    description: Recording that a library scan finished.
  - name: Events
    description: A user's matched event history.
  - name: Stats
    description: Profile statistics derived from the event history.
paths:
  /users/{user_id}/events:
    get:
      tags:
        - Events
      summary: List a user's matched events
      description: >
        The user's attended-event history, newest first, with the matched media
        attached to

        each event.


        This is everything an events tab and an event detail screen need. The
        media for an

        event is included here, so opening an event costs no extra request.


        Hidden events, and events not licensed for redistribution, are filtered
        out and never

        appear.
      operationId: listUserEvents
      parameters:
        - $ref: '#/components/parameters/UserId'
        - name: limit
          in: query
          description: Events per page.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: cursor
          in: query
          description: Opaque cursor from `next_cursor` on the previous page.
          schema:
            type: string
        - name: include_media
          in: query
          description: Set `false` for a lighter payload when you only need the event list.
          schema:
            type: boolean
            default: true
      responses:
        '200':
          description: A page of matched events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    UserId:
      name: user_id
      in: path
      required: true
      description: The FanFeed user id returned by `POST /users`.
      schema:
        type: string
        format: uuid
        examples:
          - 8f14e45f-ceea-467a-9a1e-2b4d9c3f0a11
  schemas:
    EventsResponse:
      properties:
        events:
          items:
            $ref: '#/components/schemas/Event'
          type: array
        next_cursor:
          description: Pass as `cursor` for the next page. `null` on the last page.
          anyOf:
            - type: string
            - type: 'null'
        has_more:
          examples:
            - false
          type: boolean
        total:
          description: >
            Total matched events for this user. May be omitted on later pages;
            page with

            `has_more` and `next_cursor`, not with `total`.
          examples:
            - 47
          anyOf:
            - type: integer
            - type: 'null'
      required:
        - events
        - has_more
      type: object
    Event:
      properties:
        id:
          examples:
            - 18012359
          type: integer
        name:
          examples:
            - Zach Bryan
          type: string
        starts_at_local:
          description: >
            Local date and time at the venue, without a timezone offset. Do not
            convert it;

            it is already the time the user experienced.
          examples:
            - '2026-06-13T19:30:00'
          type: string
        venue:
          anyOf:
            - $ref: '#/components/schemas/Venue'
            - type: 'null'
        performers:
          anyOf:
            - items:
                $ref: '#/components/schemas/Performer'
              type: array
            - type: 'null'
        media_count:
          examples:
            - 12
          anyOf:
            - type: integer
            - type: 'null'
        media:
          description: >-
            Present unless `include_media=false`. Complete for the event; not
            capped.
          anyOf:
            - items:
                $ref: '#/components/schemas/EventMedia'
              type: array
            - type: 'null'
      required:
        - id
        - name
        - starts_at_local
      type: object
    Error:
      description: The published error envelope.
      properties:
        error:
          description: The ``error`` member of the envelope.
          properties:
            code:
              $ref: '#/components/schemas/ErrorCode'
              description: Stable, machine-readable error code.
            message:
              description: Human-readable explanation. Not intended for end users.
              examples:
                - Send at most 200 media items per request.
              type: string
            details:
              description: >
                Optional per-field or per-item context. Present only where it
                adds something;

                its shape varies by code.
              anyOf:
                - additionalProperties: true
                  type: object
                - type: 'null'
          required:
            - code
            - message
          type: object
      required:
        - error
      type: object
    Venue:
      properties:
        id:
          examples:
            - 4412
          type: integer
        name:
          examples:
            - Madison Square Garden
          type: string
        city:
          examples:
            - New York
          anyOf:
            - type: string
            - type: 'null'
        region:
          examples:
            - NY
          anyOf:
            - type: string
            - type: 'null'
        country:
          examples:
            - US
          anyOf:
            - type: string
            - type: 'null'
        latitude:
          examples:
            - 40.750504
          anyOf:
            - type: number
            - type: 'null'
          format: double
        longitude:
          examples:
            - -73.993439
          anyOf:
            - type: number
            - type: 'null'
          format: double
      required:
        - id
        - name
      type: object
    Performer:
      properties:
        id:
          examples:
            - 34421
          type: integer
        name:
          examples:
            - Zach Bryan
          type: string
        category:
          description: Genre for music, league for sport.
          examples:
            - Country
          anyOf:
            - type: string
            - type: 'null'
        image_url:
          anyOf:
            - type: string
            - type: 'null'
          format: uri
        is_headliner:
          examples:
            - true
          anyOf:
            - type: boolean
            - type: 'null'
      required:
        - id
        - name
      type: object
    EventMedia:
      properties:
        media_id:
          description: Your `id` for the asset, as originally submitted.
          examples:
            - B84E8479-475C-4727-A4A4-B77AA9980897/L0/001
          type: string
        taken_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
        media_type:
          anyOf:
            - enum:
                - photo
                - video
              type: string
            - type: 'null'
        thumbnail_url:
          description: >
            The `thumbnail_url` you submitted for this asset. Absent when you
            did not send

            one; FanFeed never generates or hosts thumbnails itself.
          anyOf:
            - format: uri
              type: string
            - type: 'null'
      required:
        - media_id
      type: object
    ErrorCode:
      description: >
        Stable, machine-readable error code. Branch on this, not on `message`.


        Note that per-item rejections inside a media batch are *not* errors: the
        request

        still returns `200` and the items appear in `rejected[]` with a
        `reason`. An

        `error.code` means the whole request failed.


        The first nine codes are published application errors. The last four are

        framework-level codes that malformed or unsupported requests can trigger
        (for

        example, a non-JSON body returns `unsupported_media_type` and an unknown
        path

        returns `not_found`). Treat any unrecognized code as a retry or fix-once
        failure

        according to the HTTP status.
      examples:
        - invalid_batch_size
      enum:
        - invalid_api_key
        - user_not_found
        - invalid_email
        - empty_batch
        - invalid_batch_size
        - invalid_media_item
        - invalid_cursor
        - rate_limited
        - internal_error
        - unsupported_media_type
        - invalid_request
        - not_found
        - method_not_allowed
      type: string
  responses:
    BadRequest:
      description: The request was malformed or failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: No FanFeed user with that id.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: >
        Rate limited. Nothing is throttled today, but the limiter exists, so
        build for this

        from day one: honor `Retry-After` and back off.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    PartnerApiKey:
      type: apiKey
      in: header
      name: X-PARTNER-API-KEY
      description: >
        Your FanFeed partner API key, issued to your organization.


        FanFeed trusts your authentication: the key identifies you, and the
        `user_id` in the

        path identifies which of your users the request is for. FanFeed performs
        no end-user

        authentication of its own.


        Treat the key as a server-side secret. See the guide for what that
        implies for the

        camera-roll ingest path, which is the one call that naturally originates
        on-device.

````