---
title: "Get available time slots"
method: GET
path: "/v1/links/{link_id}/slots"
tags: ["Scheduling Links"]
---

# Get available time slots

`GET /v1/links/{link_id}/slots`

## Request

- Base URL: `https://api.savvycal.com`
- URL: `https://api.savvycal.com/v1/links/{link_id}/slots`
- Auth: one of:
  - OAuth 2
    - Authorization code: `/oauth/authorize`
    - Token URL: `/oauth/token`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/savvycal/apis/savvycal-meetings-api/docs/v1/links/:link_id/slots/get.ts> (a function with typed inputs; its response is checked against the schema)

If the link organizer has configured multiple durations, we'll return all possible time slots for each duration. For example, if the organizer allows schedulers to book either 30 or 60 minutes, then you may see slots that start at the same time (or overlap) with different durations:

```javascript
[
  {
    start_at: "2021-06-01T00:00:00Z",
    end_at: "2021-06-01T00:30:00Z",
    duration: 30,
    rank: 1
  },
  {
    start_at: "2021-06-01T00:00:00Z",
    end_at: "2021-06-01T01:00:00Z",
    duration: 60,
    rank: 1
  }
]
```

If the organizer is using ranked availability, then the response may include slots with different `rank` values:

```javascript
[
  // A slot with "first" preference
  {
    start_at: "2021-06-01T00:00:00Z",
    end_at: "2021-06-01T00:30:00Z",
    duration: 30,
    rank: 1
  },
  // A slot with "second" preference
  {
    start_at: "2021-06-01T03:00:00Z",
    end_at: "2021-06-01T03:30:00Z",
    duration: 60,
    rank: 2
  }
]
```

Slots with rank `1` are those the organizer prefers the most. Slots with rank `2` (and higher) will include all the slot times from lower ranks, plus additional times available in that rank. This means if you want to get the "expanded" availability (e.g. up to rank 2), you simply need to filter the list for slots where `rank === 2` (not where `rank === 1 || rank === 2`).

Here's some JavaScript pseudo-code to demonstrate:

```javascript
const slots = await fetchSlots();

// Includes just the rank 1 times
const preferredAvailability = slots.filter(({ rank }) => rank === 1);

// Includes all rank 1 AND rank 2 times
const expandedAvailability = slots.filter(({ rank }) => rank === 2);

// Includes all rank 1, rank 2 and rank 3 times
const moreExpandedAvailability = slots.filter(({ rank }) => rank === 3);
```

## Path parameters

- `link_id` string, required

## Query parameters

- `from` string, date-time
- `until` string, date-time

## Response `200`

Success

- LinkSlot[]
  - `duration` integer, required: Duration in minutes
  - `end_at` string, date-time, required
  - `rank` integer, required: Availability rank. `1` is the organizer's most preferred.
  - `start_at` string, date-time, required

## Other responses

- `400`: Slots could not be computed
- `401`: Unauthorized
- `404`: Not Found
- `422`: Invalid `from` or `until`

---

[API](https://skmtc.dev/savvycal/apis/savvycal-meetings-api.md) - [All operations](https://skmtc.dev/savvycal/apis/savvycal-meetings-api/llms.txt) - [OpenAPI document](https://skmtc.dev/savvycal/apis/savvycal-meetings-api/revisions/398985d699a3?raw)