> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/time-tracking/7shifts.md).

# 7shifts

Connect 7shifts to Coupler.io to export scheduling, time punches, and labor cost data to Google Sheets, BigQuery, or databases automatically.

7shifts is a restaurant workforce management platform built for scheduling, time tracking, and labor cost control. Managers use it to publish shift schedules, track employee clock-ins and clock-outs, manage roles and wages across multiple locations, and keep their teams organized. By connecting 7shifts to Coupler.io, you can automatically export your scheduling and time-tracking data to spreadsheets, BI tools, or databases — without manual exports or custom API work.

Coupler.io's 7shifts integration connects via **OAuth** and supports 13 data entities covering your full organizational structure, employee roster, shift schedules, time punch records, and pre-aggregated labor reports.

## Why connect 7shifts to Coupler.io?

* **Automate payroll data exports** — Pull time punch records on a schedule so your payroll team always has accurate clock-in and clock-out data, broken down by employee, role, and location.
* **Track labor costs vs. scheduled hours** — Combine shifts and wages data in a spreadsheet or BI tool to compare scheduled vs. actual labor hours across locations and departments.
* **Build scheduling dashboards** — Export shift and assignment data to analyze coverage gaps, open shifts, and workload distribution over time.
* **Flexible destinations** — Export to AI tools, Google Sheets, Excel, BigQuery, Looker Studio, or other supported destinations.

## Prerequisites

Before connecting, make sure you have:

* A **7shifts** account. Admin or manager-level access is recommended to ensure full data access across all locations and departments.
* A Coupler.io account.

## Quick start

{% hint style="success" %}
Start with the **Time punches** entity. Set the Start date to the first day of your current pay period using the date picker, then run the import and verify the hours look correct for a few employees. Once confirmed, set up a daily auto-refresh to keep your payroll data current automatically.
{% endhint %}

## How to connect

7shifts uses **OAuth authentication** — you sign in with your 7shifts account directly.

{% stepper %}
{% step %}
In Coupler.io, create a new **data flow** and select **7shifts** as the source.\
Click **Connect** and complete the OAuth login with your 7shifts credentials.
{% endstep %}

{% step %}
Grant Coupler.io permission to access your account data.
{% endstep %}

{% step %}
Select a **data entity** from the dropdown. Each data flow exports one entity at a time — for example, **Time punches** for payroll data, **Shifts** for schedule analysis, or **Users** for your employee roster.
{% endstep %}

{% step %}
Set the **Start date** using the date picker. Coupler.io pulls data from this date onwards. For time punches, use the first day of your current pay period. For historical shift data, choose a date that covers your analysis window.
{% endstep %}

{% step %}
Choose your **destination** and run the import.
{% endstep %}
{% endstepper %}

## 7shifts data overview

Coupler.io's 7shifts integration pulls data from the 7shifts API using OAuth. You select one entity per data flow — from your organizational structure (Companies, Locations, Departments, Roles) to employee and wage records (Users, Wages, Assignments) to operational data (Shifts, Time punches) to pre-aggregated labor reports (Worked hours and wages).

## What data is available?

The integration covers four natural groups of data:

* **Organizational structure** — your company hierarchy, locations, departments, and job roles
* **Employee management** — employee profiles, pay rates, and assignments across locations and departments
* **Time & scheduling** — published shift schedules and actual clock-in/clock-out records
* **Labor reports** — pre-aggregated worked hours and wages summaries per employee, role, and day

## When to use it

Use the 7shifts integration when you need to:

* Analyze actual hours worked vs. scheduled hours for labor cost control
* Build payroll-ready time punch exports broken down by employee, role, and location
* Track staffing coverage across departments and shifts over time
* Maintain a live roster of employees and their role assignments for operations reporting

## Available entities

### Organizational structure

#### Companies

The top-level record for your 7shifts account. Most accounts have one company, but multi-brand or franchise groups may have more.

| Field      | Description                         |
| ---------- | ----------------------------------- |
| `id`       | Unique company identifier           |
| `name`     | Company name                        |
| `industry` | Industry type (e.g., Restaurant)    |
| `timezone` | Company default timezone            |
| `created`  | Date the company record was created |

#### Locations

Your physical restaurant or store locations. Each location sits under a company and has its own departments and roles.

| Field         | Description                |
| ------------- | -------------------------- |
| `id`          | Unique location identifier |
| `company_id`  | Parent company ID          |
| `name`        | Location name              |
| `address`     | Street address             |
| `city`        | City                       |
| `state`       | State or province          |
| `country`     | Country                    |
| `postal_code` | Postal or ZIP code         |
| `timezone`    | Location timezone          |
| `status`      | Active or inactive         |

#### Departments

Operational departments within a location, such as Kitchen, Front of House, or Bar.

| Field         | Description                     |
| ------------- | ------------------------------- |
| `id`          | Unique department identifier    |
| `location_id` | Parent location ID              |
| `name`        | Department name                 |
| `position`    | Sort order within the location  |
| `created`     | Date the department was created |

#### Roles

Job titles or positions that employees can be assigned to, such as Server, Cook, or Bartender.

| Field           | Description                     |
| --------------- | ------------------------------- |
| `id`            | Unique role identifier          |
| `location_id`   | Location the role belongs to    |
| `department_id` | Department the role belongs to  |
| `name`          | Role name                       |
| `color`         | Color used in the schedule view |
| `sort`          | Display order                   |
| `created`       | Date the role was created       |

### Employee management

#### Users

All employees and managers in your 7shifts account, including their personal details and account status.

| Field           | Description                        |
| --------------- | ---------------------------------- |
| `id`            | Unique user identifier             |
| `company_id`    | Parent company ID                  |
| `first_name`    | Employee first name                |
| `last_name`     | Employee last name                 |
| `email`         | Employee email address             |
| `mobile_number` | Mobile phone number                |
| `employee_id`   | External employee or payroll ID    |
| `type`          | Account type (employee or manager) |
| `status`        | Active or inactive                 |
| `hired_at`      | Hire date                          |
| `created`       | Date the user record was created   |

#### Wages

Pay rates for each employee, broken down by role and location. One employee may have multiple wage records if they work different roles at different rates.

| Field         | Description                      |
| ------------- | -------------------------------- |
| `id`          | Unique wage record identifier    |
| `user_id`     | Employee ID                      |
| `location_id` | Location the wage applies to     |
| `role_id`     | Role the wage applies to         |
| `wage`        | Pay rate amount                  |
| `wage_type`   | Wage type (hourly or salary)     |
| `created`     | Date the wage record was created |

#### Assignments

General assignment records linking an employee to a location, department, or role.

| Field           | Description                     |
| --------------- | ------------------------------- |
| `id`            | Unique assignment identifier    |
| `user_id`       | Employee ID                     |
| `location_id`   | Location ID                     |
| `department_id` | Department ID                   |
| `role_id`       | Role ID                         |
| `created`       | Date the assignment was created |

#### Location assignments

Records that authorize each employee to work at a specific location.

| Field             | Description                             |
| ----------------- | --------------------------------------- |
| `id`              | Unique record identifier                |
| `user_id`         | Employee ID                             |
| `location_id`     | Location the employee is authorized for |
| `primary_role_id` | Default role at this location           |
| `created`         | Date the assignment was created         |

#### Department assignments

Records that link employees to the departments they work in.

| Field           | Description                            |
| --------------- | -------------------------------------- |
| `id`            | Unique record identifier               |
| `user_id`       | Employee ID                            |
| `department_id` | Department the employee is assigned to |
| `location_id`   | Location context                       |
| `created`       | Date the assignment was created        |

#### Role assignments

Records that link employees to the specific roles they are qualified to perform.

| Field         | Description                                 |
| ------------- | ------------------------------------------- |
| `id`          | Unique record identifier                    |
| `user_id`     | Employee ID                                 |
| `role_id`     | Role the employee can perform               |
| `location_id` | Location context                            |
| `primary`     | Whether this is the employee's primary role |
| `created`     | Date the assignment was created             |

### Time & scheduling

#### Time punches

Clock-in and clock-out records for each employee. This is the primary entity for payroll and hours-worked analysis.

| Field           | Description                                      |
| --------------- | ------------------------------------------------ |
| `id`            | Unique time punch identifier                     |
| `user_id`       | Employee who clocked in                          |
| `location_id`   | Location where the punch was recorded            |
| `department_id` | Department the punch is attributed to            |
| `role_id`       | Role the employee worked during this punch       |
| `clocked_in`    | Clock-in timestamp                               |
| `clocked_out`   | Clock-out timestamp                              |
| `hours`         | Total hours worked (decimal)                     |
| `breaks`        | Total break time (minutes)                       |
| `status`        | Punch status (e.g., active, deleted)             |
| `approved`      | Whether the punch has been approved by a manager |

#### Shifts

Scheduled work shifts for each employee, representing planned coverage rather than actual attendance.

| Field           | Description                                         |
| --------------- | --------------------------------------------------- |
| `id`            | Unique shift identifier                             |
| `user_id`       | Employee assigned to the shift (null if open shift) |
| `location_id`   | Location for the shift                              |
| `department_id` | Department for the shift                            |
| `role_id`       | Role required for the shift                         |
| `start`         | Scheduled start timestamp                           |
| `end`           | Scheduled end timestamp                             |
| `notes`         | Manager notes on the shift                          |
| `status`        | Shift status (draft, published, deleted)            |
| `published`     | Whether the shift has been published to employees   |
| `created`       | Date the shift record was created                   |

{% hint style="info" %}
Open shifts (not yet assigned to an employee) appear in the Shifts entity with `user_id` as null. If you're calculating scheduled hours, filter to only shifts where `user_id` is not null — or keep open shifts if you want to analyze staffing gaps.
{% endhint %}

### Labor reports

#### Worked hours and wages

A pre-aggregated summary of worked hours, wages, and tips per employee per day. This entity saves you from having to join and aggregate Time punches with Wages yourself — 7shifts calculates the totals and Coupler.io exports the result directly.

| Field            | Description                            |
| ---------------- | -------------------------------------- |
| `date`           | Reporting date                         |
| `user_id`        | Employee ID                            |
| `location_id`    | Location where hours were worked       |
| `department_id`  | Department the hours are attributed to |
| `role_id`        | Role the employee worked               |
| `hours`          | Total hours worked                     |
| `wages`          | Total wages for the period             |
| `tips`           | Tips recorded (if applicable)          |
| `overtime_hours` | Overtime hours for the period          |

{% hint style="success" %}
Use the **Worked hours and wages** entity when you want daily labor cost totals without building complex joins. It's ideal for dashboards that display total labor spend per location, department, or employee — without needing to combine multiple entities in your destination.
{% endhint %}

## Common data combinations

| Goal                         | Configuration                                                                                                  |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Quick labor cost report      | **Worked hours and wages** — pre-aggregated daily totals per employee and role, no joins required              |
| Payroll hours report         | Time punches + Users (join on `user_id`) — shows hours per employee per pay period                             |
| Detailed labor cost analysis | Time punches + Wages (join on `user_id` and `role_id`) — multiply `hours` × `wage` for punch-level granularity |
| Scheduled vs. actual hours   | Shifts + Time punches (join on `user_id`, match by date) — compare scheduled and worked hours                  |
| Employee roster              | Users + Location assignments + Role assignments — full picture of who works where                              |
| Department coverage          | Shifts filtered by `department_id` — analyze shift count and hours by department over time                     |

## Use cases by role

#### Operations manager

Pull Shifts and Time punches daily to compare scheduled vs. actual hours for each location. Use Wages data to calculate labor cost per shift and identify where costs are running over budget. Set up a daily refresh to keep your labor dashboard current for the morning standup.

#### Payroll administrator

Export Time punches at the end of each pay period using the date picker to define the exact range. Join with Users to get employee names and IDs, and with Wages to calculate gross pay by role. Combine multiple location data flows in one destination sheet using Coupler.io's data join feature.

#### General manager / multi-unit operator

Use Locations and Departments to build a clean org structure reference table, then join it to Time punches and Shifts for location-level reporting. Track department-level hours and labor percentages across all your locations in a single dashboard.

#### HR / workforce analyst

Pull Users, Location assignments, and Role assignments to maintain an up-to-date employee roster with role qualifications. Use hire dates and status fields to track headcount changes over time and analyze turnover rates.

## Platform-specific notes

* **One entity per data flow** — Each Coupler.io data flow exports one 7shifts entity. To combine entities (e.g., Time punches + Users), create separate data flows and use Coupler.io's data join feature to merge them by a shared key like `user_id`.
* **Start date is required** — All data flows require a Start date. Data before this date will not be included. Use the date picker to set the exact start of your reporting window.
* **Early access** — The 7shifts integration is currently in early access. If you don't see it in your Coupler.io account, contact support to have it enabled.
* **Assignment entities** — Assignments, Location assignments, Department assignments, and Role assignments all describe the same concept (which employees work where and in what role) from different angles. For most reporting needs, Role assignments or Location assignments provide the clearest picture.
* **Open shifts** — Shifts without an assigned employee (`user_id` is null) represent open shifts posted for employees to claim. Include or exclude them depending on your analysis.
* **Worked hours and wages** — This report entity provides pre-computed daily labor totals. Use it for high-level dashboards. For punch-level detail (individual clock-ins, break deductions, approval status), use Time punches instead.

## 7shifts common issues

### Connection issues

<details>

<summary>OAuth login fails or loops back to the connect screen</summary>

**Problem:** Clicking **Connect** opens the 7shifts OAuth screen but the connection doesn't complete, or you're redirected back to Coupler.io without a successful connection.

**Fix:**

1. Disable browser popup blockers and ad blockers for `coupler.io` and `app.7shifts.com`.
2. Clear browser cookies and try again in an incognito or private window.
3. Make sure you're signing in with the 7shifts account that has the data you want to export — not a personal account with limited access.
4. If the issue persists, try a different browser and contact support.

</details>

<details>

<summary>Connection drops or reconnection is needed</summary>

**Problem:** A previously working data flow suddenly fails with an authentication or connection error.

**Fix:**

1. Go to your Coupler.io connections and reconnect your 7shifts account by going through the OAuth flow again.
2. Make sure the 7shifts user whose account you connected is still active and has not had their role changed or revoked.
3. Re-run the data flow after reconnecting.

</details>

### Missing data

<details>

<summary>Data flow runs but returns no rows</summary>

**Problem:** The data flow completes without errors but the destination has no data.

**Fix:**

1. Check your **Start date** — if it's set to a future date, no records will be returned. Use the date picker to set a date in the past that covers the period you need.
2. Verify that the selected entity actually has data in your 7shifts account. For example, if no time punches have been recorded for the date range, the Time punches export will be empty.
3. Check that the connected 7shifts account has access to the locations where the data lives. A manager with limited location access may not see all records.

</details>

<details>

<summary>Missing employees or locations in the export</summary>

**Problem:** Some employees or locations appear in 7shifts but are missing from the Coupler.io export.

**Fix:**

1. Inactive users or archived locations may be excluded by default. Check whether the missing records are marked as inactive in 7shifts.
2. The connected 7shifts account must have access to the location you're trying to export. If you're a location manager (not an admin), you may only see your own location's data. Reconnect with an admin account for full access.

</details>

<details>

<summary>Time punches entity is missing recent records</summary>

**Problem:** Time punches from the last few hours or the current day don't appear in the export.

**Fix:**

1. Unapproved or in-progress punches (an employee who is currently clocked in) may not yet be finalized in the API. Check the `approved` field — only approved punches are typically included in payroll-ready exports.
2. Check the `clocked_out` field — a punch without a clock-out time is still in progress and may appear differently than completed punches.
3. Allow a short delay and re-run the data flow after the shift is completed and approved.

</details>

### Permissions issues

<details>

<summary>Some locations or departments are not visible in the export</summary>

**Problem:** You can see certain locations in your 7shifts dashboard, but they don't appear in the Coupler.io export.

**Fix:**

1. The 7shifts OAuth token is tied to the account that completed the connection. If that user is a location-level manager (not a company admin), the API will only return data for their authorized locations.
2. Reconnect using a **company admin** account to ensure access to all locations, departments, and employees across the organization.
3. Check whether the location is active — archived or deleted locations may not be returned.

{% hint style="warning" %}
For multi-location restaurant groups, always connect with a company admin account to ensure complete data access across all locations.
{% endhint %}

</details>

### Data discrepancies

<details>

<summary>Hours in Coupler.io don't match the 7shifts timesheets view</summary>

**Problem:** The total hours in your export don't match what you see in the 7shifts Timesheets report.

**Fix:**

1. Check the **Start date** on your data flow — the Coupler.io export only includes punches on or after this date. The 7shifts Timesheets view may use a different date range.
2. Check the `approved` field — if the Timesheets view only shows approved punches and your export includes unapproved ones (or vice versa), totals will differ.
3. Breaks are tracked separately in the `breaks` field (in minutes). Verify whether the 7shifts UI deducts breaks from total hours and apply the same logic in your analysis.
4. Time zones matter — the `clocked_in` and `clocked_out` fields are in UTC. Convert to the location's timezone before comparing with the 7shifts UI, which displays in local time.

</details>

<details>

<summary>Shifts data shows open shifts mixed in with scheduled shifts</summary>

**Problem:** Your shift count or hours totals are inflated because unassigned open shifts are included.

**Fix:** Filter your data to only include rows where `user_id` is not null. Open shifts (available for employees to claim) have a null `user_id`. If you only want scheduled shifts with assigned employees, exclude null `user_id` rows in your spreadsheet or BI tool.

</details>

### Rate limits and timeouts

<details>

<summary>Data flow times out on large date ranges</summary>

**Problem:** A data flow for Time punches or Shifts times out when pulling several months of history.

**Fix:**

1. Shorten the date range by moving the **Start date** closer to today. For ongoing payroll exports, you only need the current pay period — not years of history.
2. Split historical exports into multiple data flows, each covering a smaller date range (e.g., one per quarter). Use Coupler.io's append mode in the destination to combine them.
3. Contact support if timeouts persist on a reasonable date range.

{% hint style="danger" %}
Pulling more than a year of Time punches for a high-volume restaurant group (many employees, multiple locations) is likely to cause timeouts. For historical analysis, pull data in quarterly chunks and combine in your destination.
{% endhint %}

</details>

## 7shifts FAQ

<details>

<summary>Can I export a pre-aggregated labor report instead of joining Time punches and Wages?</summary>

Yes — use the **Worked hours and wages** entity. This report, generated by 7shifts, provides daily totals for hours worked, wages, and tips per employee and role without requiring you to join and aggregate raw punch data yourself.

It's the fastest way to get a labor cost summary into a spreadsheet or BI tool. If you need punch-level detail (individual clock-in/out records, break time, approval status), use the Time punches entity instead.

{% hint style="info" %}
See [Data Overview](#worked-hours-and-wages) for the full list of fields available in this report entity.
{% endhint %}

</details>

<details>

<summary>Can I export all 7shifts entities in one data flow?</summary>

No — each Coupler.io data flow exports one entity at a time. To combine data from multiple entities (for example, Time punches with Users or Wages), create a separate data flow for each entity and then use Coupler.io's **data join** feature to merge them in your destination using a shared key like `user_id`.

{% hint style="info" %}
See [Data Overview](#7shifts-data-overview) for a list of common entity combinations and the join keys to use.
{% endhint %}

</details>

<details>

<summary>What Start date should I use for the Time punches entity?</summary>

For regular payroll exports, set the Start date to the first day of your current pay period using the date picker. This pulls only the punches you need for the upcoming payroll run.

For historical analysis (e.g., quarterly labor cost review), set the Start date to the beginning of the period you want to analyze. If you need more than one quarter of history, consider splitting into multiple data flows — one per quarter — to avoid timeouts.

</details>

<details>

<summary>Can I filter time punches by location or department?</summary>

The 7shifts integration does not currently support server-side filtering by location or department. However, the Time punches entity includes `location_id` and `department_id` columns for every punch. Once the data is in your destination (Google Sheets, BigQuery, etc.), you can filter or pivot by those columns to focus on specific locations or departments.

To get the location or department name alongside the ID, create a separate data flow for Locations or Departments and use a data join to match on `location_id` or `department_id`.

</details>

<details>

<summary>Why does my hours total differ from the 7shifts Timesheets report?</summary>

A few common reasons:

* **Date range mismatch** — Check that your Start date matches the exact period shown in the 7shifts Timesheets view.
* **Approval status** — The Timesheets report in 7shifts may only include approved punches. Check the `approved` field in your export and filter accordingly.
* **Breaks** — The `hours` field includes or excludes break time depending on your 7shifts configuration. Check whether the `breaks` field (in minutes) should be deducted from `hours` to match your payroll policy.
* **Time zones** — Timestamps are in UTC. If you're summing hours by calendar day, make sure you're converting to local time first.

</details>

<details>

<summary>How do I calculate labor cost from 7shifts data?</summary>

Combine two data flows:

1. **Time punches** — provides `hours`, `user_id`, and `role_id` for each punch
2. **Wages** — provides `wage` and `wage_type` per employee and role

Join on both `user_id` and `role_id`, then multiply `hours` × `wage` for each punch to get the labor cost. An employee can have different pay rates for different roles, so joining on both keys ensures you use the correct rate for each shift worked.

{% hint style="info" %}
See [Best Practices](/sources/category/time-tracking/7shifts/best-practices.md) for guidance on joining Time punches with Wages and handling break time in cost calculations.
{% endhint %}

</details>

<details>

<summary>What's the difference between Assignments, Location assignments, Department assignments, and Role assignments?</summary>

All four entities describe relationships between employees and their work setup, but from different angles:

* **Assignments** — a general record linking a user to a location, department, and role in one row
* **Location assignments** — specifically records which locations an employee is authorized to work at
* **Department assignments** — records which departments an employee belongs to
* **Role assignments** — records which roles an employee is qualified to perform, including whether it's their primary role

For most reporting purposes, **Role assignments** and **Location assignments** are the most useful. Use them to build a lookup table of which employees work where and in what capacity.

</details>

<details>

<summary>What does it mean when a shift has no user_id?</summary>

A shift with a null `user_id` is an **open shift** — a shift that has been posted to the schedule for any qualified employee to claim, but hasn't been assigned yet. Open shifts appear in the Shifts entity alongside scheduled shifts.

When calculating scheduled hours per employee, filter to rows where `user_id` is not null. If you want to analyze unfilled staffing gaps, look at shifts where `user_id` is null and `published` is true.

</details>

<details>

<summary>Why don't I see all my locations in the export?</summary>

The data returned by the 7shifts API is scoped to the account used during the OAuth connection. If the connected account is a location manager (not a company admin), the API will only return data for locations that user has access to.

To get data from all locations, reconnect Coupler.io using a **company admin** 7shifts account.

{% hint style="info" %}
See [Common Issues](#7shifts-common-issues) for more troubleshooting steps related to missing locations and permission errors.
{% endhint %}

</details>

<details>

<summary>Is 7shifts available to all Coupler.io users?</summary>

The 7shifts integration is currently in **early access**. It may not be visible in all Coupler.io accounts by default. If you don't see 7shifts in the source list, contact Coupler.io support to have it enabled for your account.

</details>

<details>

<summary>How often should I refresh 7shifts data?</summary>

It depends on the entity:

| Entity                        | Recommended refresh                    |
| ----------------------------- | -------------------------------------- |
| Time punches                  | Daily (or after each pay period close) |
| Shifts                        | Daily during active scheduling weeks   |
| Users                         | Weekly                                 |
| Wages                         | Weekly or on change                    |
| Locations, Departments, Roles | Monthly                                |
| Assignments                   | Weekly                                 |

For payroll-critical exports, schedule a final refresh a few hours after the last shift of your pay period ends to capture all manager approvals.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/time-tracking/7shifts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.