--- updatedAt: 2026-06-29T07:51:26.000Z --- Fetch the complete documentation index at: https://developer.connecteam.com/llms.txt. Use this file to discover all available pages before exploring further. # Getting Shifts Retrieve shifts from a scheduler with flexible filtering and pagination options. > 📘 JS Vision (Scheduler V2) > > This page documents the standard **V1** API. On a JS Vision–migrated company, V1 returns **one row per assigned user**, while **Scheduler V2** returns **one aggregated shift** per group (with all users in `assignedUserIds`). See [JS Vision: V1 vs V2 Shifts API](https://developer.connecteam.com/docs/scheduler-shifts-vision). ## Endpoints | Method | Endpoint | Description | | :----- | :------------------------------------------------------ | :------------------ | | GET | /scheduler/v1/schedulers/{schedulerId}/shifts | Get multiple shifts | | GET | /scheduler/v1/schedulers/{schedulerId}/shifts/{shiftId} | Get a single shift | *** ## Get Multiple Shifts Retrieve shifts with optional filters. ### Path Parameters | Parameter | Type | Required | Description | | :---------- | :------ | :------- | :------------------------ | | schedulerId | integer | Yes | The scheduler's unique ID | ### Query Parameters | Parameter | Type | Required | Default | Description | | :--------------------- | :------ | :------- | :----------- | :---------------------------------------------- | | startTime | integer | **Yes** | - | Start of date range (Unix timestamp in seconds) | | endTime | integer | **Yes** | - | End of date range (Unix timestamp in seconds) | | isOpenShift | boolean | No | - | Filter by open shift status | | isPublished | boolean | No | - | Filter by published status | | isRequireAdminApproval | boolean | No | - | Filter shifts requiring approval | | jobId | array | No | - | Filter by job IDs | | assignedUserIds | array | No | - | Filter by assigned user IDs | | shiftId | array | No | - | Filter by specific shift IDs | | title | string | No | - | Filter by shift title (partial match) | | sort | string | No | `created_at` | Sort by `created_at` or `updated_at` | | order | string | No | `asc` | Sort order: `asc` or `desc` | | limit | integer | No | 10 | Results per page (1-500) | | offset | integer | No | 0 | Pagination offset | > ⚠️ Required Parameters > > `startTime` and `endTime` are **required**. The API will return a 422 error if these are missing. > 📝 Note on Time Range > > Shifts are returned if they overlap with the specified time range. A shift starting before `startTime` but ending after it will be included. *** ### Example: Basic Query ```bash curl --request GET \ --url 'https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts?startTime=1736899200&endTime=1737504000' \ --header 'X-API-KEY: YOUR_API_KEY' ``` ### Example: Filter by Job and User ```bash curl --request GET \ --url 'https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts?startTime=1736899200&endTime=1737504000&jobId=job-123&assignedUserIds=9170357&assignedUserIds=9170358' \ --header 'X-API-KEY: YOUR_API_KEY' ``` ### Example: Get Open Shifts Requiring Approval ```bash curl --request GET \ --url 'https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts?startTime=1736899200&endTime=1737504000&isOpenShift=true&isRequireAdminApproval=true&isPublished=true' \ --header 'X-API-KEY: YOUR_API_KEY' ``` ### Example: Paginated Results ```bash curl --request GET \ --url 'https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts?startTime=1736899200&endTime=1737504000&limit=50&offset=100&sort=updated_at&order=desc' \ --header 'X-API-KEY: YOUR_API_KEY' ``` *** ### Response ```json { "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "data": { "shifts": [ { "id": "6784dacb3c07733b0a849f49", "title": "Morning Shift", "color": "#4B7AC5", "assignedUserIds": [9170357], "startTime": 1736924400, "endTime": 1736953200, "timezone": "America/New_York", "isOpenShift": false, "isPublished": true, "isRequireAdminApproval": null, "jobId": "d4ad7232-576f-2ff6-c57d-8240f1089b00", "locationData": { "isReferencedToJob": true, "gps": { "address": "123 Main Street, New York, NY", "latitude": 40.7579747, "longitude": -73.9855426 } }, "createdBy": 9170357, "creationTime": 1736760011, "updateTime": 1736760011, "openSpots": null, "notes": [ { "type": "html", "html": "

Remember to check inventory

" } ], "statuses": [ { "statusId": "status-001", "status": "accepted", "creatingUserId": 9170357, "creationTime": 1736760100, "assignedUserId": 9170357 } ], "breaks": [ { "id": "break-001", "name": "Lunch", "type": "unpaid", "startTime": 720, "duration": 30 } ], "shiftDetails": { "shiftLayers": [ { "id": "layer-dept-001", "title": "Department", "value": { "id": "value-sales-001", "displayName": "Sales" } } ], "shiftSource": null }, "customFields": [ { "id": "field_abc123", "title": "Project Code", "value": "PROJ-2024-001" }, { "id": "field_def456", "title": "Cost Center", "value": "CC-Operations" } ] } ] }, "paging": { "offset": 1 } } ``` *** ## Get Single Shift Retrieve a specific shift by its ID. ### Path Parameters | Parameter | Type | Required | Description | | :---------- | :------ | :------- | :------------------------ | | schedulerId | integer | Yes | The scheduler's unique ID | | shiftId | string | Yes | The shift's unique ID | ### Example ```bash curl --request GET \ --url https://api.connecteam.com/scheduler/v1/schedulers/9454799/shifts/6784dacb3c07733b0a849f49 \ --header 'X-API-KEY: YOUR_API_KEY' ``` ### Response ```json { "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "data": { "id": "6784dacb3c07733b0a849f49", "title": "Morning Shift", "color": "#4B7AC5", "assignedUserIds": [9170357], "startTime": 1736924400, "endTime": 1736953200, "timezone": "America/New_York", "isOpenShift": false, "isPublished": true, "isRequireAdminApproval": null, "jobId": "d4ad7232-576f-2ff6-c57d-8240f1089b00", "locationData": { "isReferencedToJob": true, "gps": { "address": "123 Main Street, New York, NY", "latitude": 40.7579747, "longitude": -73.9855426 } }, "createdBy": 9170357, "creationTime": 1736760011, "updateTime": 1736760011, "openSpots": null, "notes": [], "statuses": [], "breaks": [], "shiftDetails": { "shiftLayers": [], "shiftSource": null }, "customFields": [ { "id": "field_abc123", "title": "Project Code", "value": "PROJ-2024-001" } ] } } ``` *** ## Response Field Details ### Shift Object | Field | Type | Nullable | Description | | :--------------------- | :------ | :------- | :--------------------------------------------------------- | | id | string | No | Unique shift identifier | | title | string | No | Shift display name | | color | string | No | Hex color code | | assignedUserIds | array | No | List of assigned user IDs (empty array if unassigned) | | startTime | integer | No | Start time (Unix timestamp) | | endTime | integer | No | End time (Unix timestamp) | | timezone | string | No | Timezone in Tz format | | isOpenShift | boolean | No | Whether shift is open for claiming | | isPublished | boolean | No | Whether shift is visible to users | | isRequireAdminApproval | boolean | Yes | Whether claims require approval (null for non-open shifts) | | jobId | string | Yes | Associated job ID | | locationData | object | Yes | Location information | | createdBy | integer | Yes | User ID of admin who created shift | | creationTime | integer | Yes | Creation timestamp | | updateTime | integer | Yes | Last update timestamp | | openSpots | integer | Yes | Number of open spots (null for non-open shifts) | | notes | array | No | Array of note objects | | statuses | array | No | Array of status objects | | breaks | array | No | Array of break objects | | shiftDetails | object | No | Shift layer values and source | | customFields | array | No | Custom field values and metadata | ### Location Data Object | Field | Type | Description | | :---------------- | :------ | :------------------------------------- | | isReferencedToJob | boolean | Whether location is inherited from job | | gps | object | GPS coordinates and address | | gps.address | string | Street address | | gps.latitude | number | Latitude (-90 to 90) | | gps.longitude | number | Longitude (-180 to 180) | ### Break Object | Field | Type | Description | | :-------- | :------ | :------------------------------------------- | | id | string | Unique break identifier | | name | string | Break display name | | type | string | `paid` or `unpaid` | | startTime | integer | Minutes from midnight (e.g., 720 = 12:00 PM) | | duration | integer | Break duration in minutes | > 📝 Note on Break Times > > Break `startTime` is expressed as minutes from midnight, not a Unix timestamp. For example, 720 means the break starts at 12:00 PM (noon). ### Status Object | Field | Type | Description | | :-------------- | :------ | :---------------------------------------------------- | | statusId | string | Unique status identifier | | status | string | Status type (see [Shifts Overview](scheduler-shifts)) | | note | string | Optional status note | | creatingUserId | integer | User who created the status | | modifyingUserId | integer | User who last modified | | creationTime | integer | Creation timestamp | | updateTime | integer | Last update timestamp | | gps | object | GPS data if location was captured | | assignedUserId | integer | User the status applies to | | attachments | array | Attached file URLs | ### Custom Field Object | Field | Type | Description | | :---- | :----------- | :------------------------ | | id | string | Custom field identifier | | title | string | Custom field display name | | value | string/array | Field value(s) | > 📝 Note on Custom Fields > > Custom fields are automatically included in shift responses when they have values. Use the [Get Custom Fields](https://developer.connecteam.com/reference/get-shift-custom-fields) endpoint to retrieve field definitions. *** ## Pagination When there are more results than the `limit`, use the `offset` from the response to fetch the next page. ```javascript async function getAllShifts(schedulerId, startTime, endTime) { const shifts = []; let offset = 0; const limit = 100; while (true) { const response = await fetch( `https://api.connecteam.com/scheduler/v1/schedulers/${schedulerId}/shifts?startTime=${startTime}&endTime=${endTime}&limit=${limit}&offset=${offset}`, { headers: { 'X-API-KEY': 'YOUR_API_KEY' } } ); const result = await response.json(); shifts.push(...result.data.shifts); if (result.data.shifts.length < limit) { break; // No more results } offset = result.paging.offset; } return shifts; } ``` *** ## Error Responses ### 400 Bad Request ```json { "detail": [ "job_id: job-invalid-123 does not exist", "assigned user ids doesn't exist: [99999999]" ] } ``` ### 422 Validation Error ```json { "detail": [ { "loc": ["query", "startTime"], "msg": "field required", "type": "value_error.missing" } ] } ``` > ⚠️ Validation Note > > The `isRequireAdminApproval` filter can only be used when `isOpenShift=true`. Using it with non-open shifts will return an error. *** [API Reference](https://developer.connecteam.com/reference/)