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

# Fetch user events

> List public events by username with filtering and pagination

## Endpoint

```http theme={null}
GET /api/public/v1/users/{username}/events
```

## Authentication

<Warning>
  This endpoint requires a public API key.
</Warning>

```http theme={null}
x-evento-api-key: YOUR_API_KEY
```

Retrieve public events created by a user, with optional filtering for time-based views.

## Path parameters

<ParamField path="username" type="string" required>
  Username (case-insensitive, no `@` prefix).
</ParamField>

## Query parameters

<ParamField query="type" type="string">
  Optional filter: `upcoming`, `past`, or `profile`.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Results per page (max 100).
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Pagination offset.
</ParamField>

## Request examples

<RequestExample>
  ```bash cURL theme={null}
  curl "https://evento.so/api/public/v1/users/johndoe/events?type=upcoming&limit=10" \
    -H "x-evento-api-key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const username = 'johndoe';
  const params = new URLSearchParams({
    type: 'upcoming',
    limit: '10',
    offset: '0'
  });

  const response = await fetch(
    `https://evento.so/api/public/v1/users/${username}/events?${params}`,
    {
      headers: {
        'x-evento-api-key': process.env.EVENTO_API_KEY
      }
    }
  );

  const payload = await response.json();
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.get(
      'https://evento.so/api/public/v1/users/johndoe/events',
      params={'type': 'upcoming', 'limit': 10, 'offset': 0},
      headers={'x-evento-api-key': os.environ['EVENTO_API_KEY']}
  )

  payload = response.json()
  ```
</RequestExample>

## Success response

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "success": true,
    "message": "Events fetched successfully",
    "data": {
      "events": [
        {
          "id": "evt_future1",
          "title": "Summer Festival 2026",
          "description": "Annual summer celebration",
          "cover": "https://cdn.evento.so/covers/future1.jpg",
          "location": "Central Park, NY",
          "start_date": "2026-06-21T14:00:00Z",
          "end_date": "2026-06-21T22:00:00Z",
          "timezone": "America/New_York",
          "status": "published",
          "visibility": "public",
          "cost": 25.0,
          "created_at": "2026-05-15T09:00:00Z",
          "creator": {
            "id": "usr_123",
            "username": "johndoe",
            "image": "https://cdn.evento.so/avatars/123.jpg",
            "verification_status": "verified"
          },
          "links": {
            "spotify_url": "https://open.spotify.com/playlist/summer2026",
            "wavlake_url": null
          },
          "contributions": {
            "cashapp": "$johndoe",
            "venmo": "@johndoe",
            "paypal": "johndoe@example.com",
            "btc_lightning": null
          }
        }
      ],
      "pagination": {
        "limit": 10,
        "offset": 0,
        "total": 1
      }
    }
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "success": false,
    "message": "Username missing or user not found"
  }
  ```
</ResponseExample>

## Filter semantics

<AccordionGroup>
  <Accordion title="upcoming">
    Returns events where `start_date >= now`.
  </Accordion>

  <Accordion title="past">
    Returns events where `start_date < now`.
  </Accordion>

  <Accordion title="profile">
    Returns profile-visible events (created by or RSVP-associated to the user).
  </Accordion>
</AccordionGroup>

## Pagination pattern

<CodeGroup>
  ```javascript Pagination Loop theme={null}
  async function getAllEventsForUser(username, apiKey) {
    const events = [];
    let offset = 0;
    const limit = 50;

    while (true) {
      const params = new URLSearchParams({
        type: 'upcoming',
        limit: String(limit),
        offset: String(offset)
      });

      const response = await fetch(
        `https://evento.so/api/public/v1/users/${username}/events?${params}`,
        { headers: { 'x-evento-api-key': apiKey } }
      );

      const json = await response.json();
      events.push(...json.data.events);

      if (offset + limit >= json.data.pagination.total) break;
      offset += limit;
    }

    return events;
  }
  ```

  ```python Pagination Loop theme={null}
  import os
  import requests


  def get_all_events_for_user(username):
      events = []
      offset = 0
      limit = 50

      while True:
          response = requests.get(
              f'https://evento.so/api/public/v1/users/{username}/events',
              params={'type': 'upcoming', 'limit': limit, 'offset': offset},
              headers={'x-evento-api-key': os.environ['EVENTO_API_KEY']}
          )

          payload = response.json()['data']
          events.extend(payload['events'])

          if offset + limit >= payload['pagination']['total']:
              break

          offset += limit

      return events
  ```
</CodeGroup>

## Use cases

<CardGroup cols={2}>
  <Card title="Organizer profiles" icon="id-badge">
    Show upcoming and past events on user profile pages.
  </Card>

  <Card title="Creator analytics" icon="chart-line">
    Build aggregate reports for event volume and cadence by organizer.
  </Card>

  <Card title="Calendar exports" icon="calendar-plus">
    Transform public schedules into external calendars and feeds.
  </Card>

  <Card title="Discovery pages" icon="compass">
    Curate creators and surface upcoming events by niche.
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Get /events/{eventId}" icon="calendar" href="/api/events">
    Retrieve a single public event.
  </Card>

  <Card title="Get /events/{eventId}/guests" icon="users" href="/api/event-guests">
    Retrieve guests and RSVP statuses.
  </Card>
</CardGroup>