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

# List Upcoming Home Page Events

> Returns published events flagged for the home page, used to populate upcoming event widgets on the portal home.

# List Upcoming Home Page Events

Returns a list of published events that the operator has flagged to appear on the portal home page (`onlyHomePage=true`). This is the shortcut endpoint behind `endpoints.events.upcomingEvents` — equivalent to calling the events list with `onlyHomePage=true`.

<Note>
  This endpoint is a convenience alias for `GET /api/public/events?onlyHomePage=true`. See [List Events](/api/endpoints/events/list-events) for the
  full parameter and response documentation.
</Note>

## Authentication

No authentication required.

## Query Parameters

<ParamField query="onlyHomePage" type="boolean" required>
  Must be `true`. Returns only events that the operator has configured to appear on the portal home page.
</ParamField>

<ParamField query="_shape" type="string">
  Comma-separated list of field paths to include in the response. When provided, only the
  specified fields are returned — useful for reducing payload size. Supports nested paths
  using dot notation. Example: `_shape=CalendarEvents.Records.Name,CalendarEvents.Records.StartDateUtc,CalendarEvents.TotalItems`.
</ParamField>

## Response

Returns the same `EventList` structure as [List Events](/api/endpoints/events/list-events). See that endpoint for the full field breakdown.

### Key Event Fields

| Field                | Type      | Description                             |
| -------------------- | --------- | --------------------------------------- |
| `Id`                 | `number`  | Unique numeric identifier for the event |
| `Name`               | `string`  | Event title (localised)                 |
| `ShortDescription`   | `string`  | Brief event description                 |
| `StartDateUtc`       | `string`  | Event start date/time (UTC)             |
| `EndDateUtc`         | `string`  | Event end date/time (UTC)               |
| `HasLargeImage`      | `boolean` | Whether the event has a large image     |
| `ShowInHomePage`     | `boolean` | Whether flagged for the home page       |
| `HasTickets`         | `boolean` | Whether the event has ticket products   |
| `SoldOut`            | `boolean` | Whether all tickets are sold out        |
| `ChepeastPrice`      | `number`  | Lowest ticket price                     |
| `MostExpensivePrice` | `number`  | Highest ticket price                    |
| `Business`           | `object`  | Location object (`Id`, `Name`)          |

## Examples

### Fetch home page events

```http theme={null}
GET /api/public/events?onlyHomePage=true
```

```json theme={null}
{
  "PastEvents": false,
  "Categories": [],
  "Category": null,
  "CalendarEvents": {
    "Records": [
      {
        "Id": 420,
        "Name": "Startup Pitch Night",
        "ShortDescription": "Watch 8 local startups pitch to a panel of investors.",
        "StartDateUtc": "2026-03-28T18:00:00Z",
        "EndDateUtc": "2026-03-28T21:00:00Z",
        "HasLargeImage": true,
        "ShowInHomePage": true,
        "HasTickets": true,
        "SoldOut": false,
        "ChepeastPrice": 0,
        "MostExpensivePrice": 25.0,
        "Business": { "Id": 5, "Name": "Downtown Coworking Hub" }
      }
    ],
    "CurrentPage": 1,
    "CurrentPageSize": 25,
    "TotalItems": 1,
    "TotalPages": 1,
    "HasNextPage": false,
    "HasPreviousPage": false
  }
}
```

## TypeScript Integration

```typescript theme={null}
import endpoints from '@/api/endpoints'

// endpoints.events.upcomingEvents is a pre-built URL string:
// 'api/public/events?onlyHomePage=true'
const { resource: upcomingEvents } = useData(httpClient, endpoints.events.upcomingEvents)
```

## Usage in Portal

| Context                                                | Source file                                                                                       |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| Upcoming Events dashboard section (personal dashboard) | `src/views/user/dashboards/personal/components/UpcomingEvents/UpcomingEventsDashboardSection.tsx` |

## Error Responses

<ResponseField name="400 Bad Request" type="error">
  Invalid query parameter value.
</ResponseField>

## Related Endpoints

| Method | Endpoint                  | Description                                 |
| ------ | ------------------------- | ------------------------------------------- |
| `GET`  | `/api/public/events`      | Full paginated events list with all filters |
| `GET`  | `/api/public/events/{id}` | Full detail for a specific event            |
| `GET`  | `/api/public/events/my`   | Tickets held by the authenticated customer  |