> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timeback.com/llms.txt
> Use this file to discover all available pages before exploring further.
# User Profile
> Fetch user profile data including XP, enrollments, and progress
## Overview
The user profile contains an enriched view of the current user, including identity information, school, grade, enrolled courses, goals, and XP totals.
You can access user data in several ways:
1. **Server-side**: verify users or fetch profiles directly from your backend
2. **Client-side**: use a framework hook with built-in state and caching
## Server-Side
The `timeback.user` namespace provides programmatic methods that accept an email directly. Use them in your own API routes, server actions, webhooks, cron jobs, or any backend context.
### Verify a user
Use `timeback.user.verify(email)` to check whether a Timeback user exists for a given email. This is a lightweight check — it does not fetch enrollments, analytics, or build an enriched profile.
```typescript TypeScript theme={null}
const result = await timeback.user.verify('student@example.com')
if (result.verified) {
console.log(result.timebackId) // "tb_abc123"
}
```
```python Python theme={null}
result = await timeback.user.verify("student@example.com")
if result.verified:
print(result.timeback_id) # "tb_abc123"
```
Useful for gating features (e.g., offering a free tier to Timeback users) without the cost of a full profile fetch.
Whether the user exists in Timeback.
The Timeback user ID. Only present when `verified` is `true`.
### Get a user profile
Use `timeback.user.getProfile(email)` to get the full enriched profile — identity, enrollments, courses, goals, and XP. This is the programmatic equivalent of the `/user/me` HTTP handler.
```typescript TypeScript theme={null}
const email = 'student@example.com'
const profile = await timeback.user.getProfile(email)
```
```python Python theme={null}
email = "student@example.com"
profile = await timeback.user.get_profile(email)
```
Throws a `TimebackUserResolutionError` if the user cannot be resolved. If you're not sure whether a user exists, call `verify()` first.
Timeback user ID.
User's email address.
Display name.
School the user belongs to.
School ID.
School name.
Grade level.
Enrolled courses matched against `timeback.config.json`.
Course ID.
Course code.
Course name.
Goals from the user's enrollment metadata.
Daily XP target.
Daily lesson target.
Daily active minutes target.
Daily accuracy target.
Daily mastered units target.
XP earned on this app. Calculated from Caliper events sent during activity tracking.
XP earned during the current UTC day.
Total XP over all time.
## Client-Side
On the client, use the framework-specific profile hook. The hook handles loading state, caching, and session-aware refetching — you never call `timeback.user.fetch()` directly from the browser.
```tsx theme={null}
import { useTimebackProfile } from '@timeback/sdk/react'
// Manual fetch
function ProfileButton() {
const { state, canFetch, fetchProfile } = useTimebackProfile()
if (state.status === 'loaded') {
return
XP: {state.profile.xp.today}
}
return (
)
}
// Auto-fetch when verified
function AutoProfile() {
const { state } = useTimebackProfile({ auto: true })
if (state.status === 'loading') return
{/if}
```
```tsx theme={null}
import { createTimebackProfile } from '@timeback/sdk/solid'
import { Show } from 'solid-js'
function ProfileButton() {
const { state, canFetch, fetchProfile } = createTimebackProfile()
return (
{state.status === 'loading' ? 'Loading...' : 'Load Profile'}
}
>
XP: {state.profile.xp.today}
)
}
```
Timeback user ID.
User's email address.
Display name.
School the user belongs to.
School ID.
School name.
Grade level.
Enrolled courses matched against `timeback.config.json`.
Course ID.
Course code.
Course name.
Goals from the user's enrollment metadata.
Daily XP target.
Daily lesson target.
Daily active minutes target.
Daily accuracy target.
Daily mastered units target.
XP earned on this app. Calculated from Caliper events sent during activity tracking.
XP earned during the current UTC day.
Total XP over all time.
### Hook State
The profile hook returns a state object with these statuses:
| Status | Description |
| --------- | --------------------------------- |
| `idle` | Initial state, no fetch attempted |
| `loading` | Fetch in progress |
| `loaded` | Profile successfully loaded |
| `error` | Fetch failed |
### Caching
The client SDK caches profile data to minimize API calls:
* Profile is fetched once per session
* Manual refetch available via `fetchProfile()`
* Cache is invalidated on sign-out
## Next Steps
Track activities to earn XP
Authentication setup
Advanced analytics queries
Query enrollments directly