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

# Sessions

> Fetch and display Boxpressd smoke session activity using SDK server functions and React hooks.

Use the Boxpressd Sites SDK to display recent smoke session activity for the business associated with your API key.

Sessions can be associated with venues, brands, cigars, and user activity depending on the data available in Boxpressd.

## Server Function

Use `getBoxpressdSessions` when fetching sessions in server components, loaders, API routes, or other server-side code.

```tsx id="q9kd9v" theme={null}
import { getBoxpressdSessions } from "@boxpressd/sites-sdk/sessions"

export default async function SessionsPage() {
  const sessions = await getBoxpressdSessions({
    limit: 10
  })

  return (
    <section>
      {sessions.map((session) => (
        <article key={session.id}>
          <p>{session.user.displayName} smoked {session.cigar?.name}</p>
          <p>{session.createdAt}</p>
        </article>
      ))}
    </section>
  )
}
```

## Function Signature

```ts id="81w9id" theme={null}
getBoxpressdSessions(options?: GetBoxpressdSessionsOptions): Promise<BoxpressdSession[]>
```

## Options

| Option | Type | Description |
| - | - | - |
| `limit` | `number` | Limits the number of sessions returned. |
| `offset` | `number` | Skips a number of sessions for pagination. |
| `from` | `string` | ISO date string used to return sessions after a date. |
| `to` | `string` | ISO date string used to return sessions before a date. |
| `featured` | `boolean` | Returns only featured sessions when supported. |

## React Hook

Use `useSessions` when fetching sessions from client components.

```tsx id="xs7yhr" theme={null}
"use client"

import { useSessions } from "@boxpressd/sites-sdk/sessions"

export function RecentSessions() {
  const {
    data: sessions,
    isLoading,
    error
  } = useSessions({
    limit: 10
  })

  if (isLoading) {
    return <p>Loading sessions...</p>
  }

  if (error) {
    return <p>Unable to load sessions.</p>
  }

  return (
    <section>
      {sessions?.map((session) => (
        <article key={session.id}>
          <p>{session.user.displayName} smoked {session.cigar?.name}</p>
          <p>{session.createdAt}</p>
        </article>
      ))}
    </section>
  )
}
```

## Hook Signature

```ts id="psp30b" theme={null}
useSessions(options?: UseSessionsOptions): {
  data: BoxpressdSession[] | undefined
  isLoading: boolean
  error: Error | null
  refetch: () => void
}
```

<Note>
  `useSessions` is planned for the SDK and may not be available until a future release.
</Note>

## Session Object

```ts id="7k4mrx" theme={null}
type BoxpressdSession = {
  id: string
  createdAt: string
  startedAt?: string
  endedAt?: string
  durationSeconds?: number
  rating?: number
  note?: string
  user: {
    id?: string
    displayName: string
    avatarUrl?: string
  }
  cigar?: {
    id: string
    name: string
    brandName?: string
    imageUrl?: string
  }
  venue?: {
    id: string
    name: string
  }
}
```

## Username Fallback

The SDK normalizes user display names when session data is returned.

The display name is resolved in this order:

```ts id="hn6o1l" theme={null}
display_name → first_name + last initial → "Boxpressd User"
```

## Example: Recent Sessions

```tsx id="37und5" theme={null}
const sessions = await getBoxpressdSessions({
  limit: 5
})
```

## Example: Date Range

```tsx id="ucceq1" theme={null}
const sessions = await getBoxpressdSessions({
  from: "2026-07-01",
  to: "2026-07-31",
  limit: 20
})
```

## Related API Endpoint

Internally, this SDK helper calls the Boxpressd API endpoint for the resolved business:

```txt id="wvmgww" theme={null}
GET /{businessType}s/{businessId}/sessions
```

For example:

```txt id="1x21fm" theme={null}
GET /venues/stogies-chapin/sessions?limit=10
```

or:

```txt id="hokav0" theme={null}
GET /brands/dreamer-cigars/sessions?limit=10
```

Most SDK users should use `getBoxpressdSessions` or `useSessions` instead of calling the API directly.

## Best Practices

* Use sessions as social proof on venue or brand websites.
* Keep public session feeds recent and concise.
* Gracefully hide the section when no sessions are available.
* Avoid exposing sensitive user details.
* Use the SDK's normalized display name instead of manually building user names.

## Next Steps

Continue to:

* Events
* Check-ins
* Components Overview
* API Reference