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

# GET /v1/calendars

> List all users who have connected their calendar to your platform

## Overview

Retrieves all calendar connections associated with your platform. This shows which users have authorized their Google Calendar through your integration.

## Authentication

Requires **Platform API Key** in the `Authorization` header or `X-API-Key` header.

## Request

```bash theme={null}
GET https://api.syncline.run/v1/calendars
```

### No Parameters Required

This endpoint returns all calendar connections for the authenticated platform.

## Response

### Success Response (200 OK)

```json theme={null}
{
  "success": true,
  "connections": [
    {
      "user_email": "alice@example.com",
      "google_id": "105942374304",
      "calendar_provider": "google",
      "connected_at": "2025-11-20T10:30:00Z",
      "last_used_at": "2025-11-21T14:22:00Z",
      "onboarding_complete": true,
      "timezone": "America/Los_Angeles"
    },
    {
      "user_email": "bob@example.com",
      "google_id": "105942374305",
      "calendar_provider": "google",
      "connected_at": "2025-11-19T08:15:00Z",
      "last_used_at": "2025-11-21T09:30:00Z",
      "onboarding_complete": true,
      "timezone": "America/New_York"
    }
  ],
  "count": 2
}
```

### Response Fields

<ResponseField name="success" type="boolean">
  Whether the request succeeded
</ResponseField>

<ResponseField name="connections" type="array">
  Array of calendar connection objects
</ResponseField>

<ResponseField name="connections[].user_email" type="string">
  Email address of the connected user
</ResponseField>

<ResponseField name="connections[].google_id" type="string">
  Google account ID for the user
</ResponseField>

<ResponseField name="connections[].calendar_provider" type="string">
  Calendar provider (currently only `"google"`)
</ResponseField>

<ResponseField name="connections[].connected_at" type="string">
  ISO 8601 timestamp when the user first connected
</ResponseField>

<ResponseField name="connections[].last_used_at" type="string">
  ISO 8601 timestamp of last API usage for this user
</ResponseField>

<ResponseField name="connections[].onboarding_complete" type="boolean">
  Whether the user completed the onboarding flow
</ResponseField>

<ResponseField name="connections[].timezone" type="string">
  User's configured timezone (IANA format)
</ResponseField>

<ResponseField name="count" type="number">
  Total number of connections returned
</ResponseField>

## Example

```javascript theme={null}
const response = await fetch('https://api.syncline.run/v1/calendars', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const result = await response.json();
console.log(`Connected users: ${result.count}`);
result.connections.forEach(conn => {
  console.log(`- ${conn.user_email} (${conn.timezone})`);
});
```

## Security Note

**OAuth tokens are sanitized** - This endpoint does not return OAuth access tokens or refresh tokens. It only returns connection metadata for security reasons.

To use a user's calendar:

1. Get their email from this endpoint
2. Use their email in scheduling API calls
3. Syncline handles OAuth token management internally

## Use Cases

### Track Active Users

Monitor which users have connected their calendars:

```javascript theme={null}
const { connections } = await listCalendars();
const activeUsers = connections.filter(c => c.onboarding_complete);
console.log(`${activeUsers.length} active users`);
```

### User Onboarding Status

Check if specific users have completed setup:

```javascript theme={null}
const { connections } = await listCalendars();
const user = connections.find(c => c.user_email === 'alice@example.com');
if (user && !user.onboarding_complete) {
  console.log('User needs to complete onboarding');
}
```

### Analytics Dashboard

Build dashboards showing connection statistics:

```javascript theme={null}
const { connections, count } = await listCalendars();
const timezones = connections.map(c => c.timezone);
const mostCommon = timezones.reduce((acc, tz) => {
  acc[tz] = (acc[tz] || 0) + 1;
  return acc;
}, {});
```

## Error Responses

<ResponseField name="401 Unauthorized" type="error">
  Invalid or missing API key
</ResponseField>

<ResponseField name="500 Internal Server Error" type="error">
  Failed to retrieve connections from database
</ResponseField>

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Disconnect Calendar" icon="link-slash" href="/api-reference/disconnect-calendar">
    Remove a calendar connection
  </Card>

  <Card title="Platform Dashboard" icon="gauge" href="/api-reference/platform-dashboard">
    View platform analytics
  </Card>
</CardGroup>