> 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/finance-and-accounting/xero.md).
# Xero
Connect Xero to Google Sheets and BI tools via Coupler.io. Export invoices, contacts, journals, and financial reports automatically without manual downloads.
Xero is a cloud-based accounting platform popular with small businesses, accountants, and bookkeepers — especially in Australia, New Zealand, and the UK. By connecting Xero to Coupler.io, you can automatically export accounting data and financial reports to spreadsheets, BI tools, or databases without manual CSV downloads.
Coupler.io offers **two Xero data sources** that cover different use cases:
| Data source | What it does |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Xero** | Pulls raw entity data — invoices, contacts, bank transactions, journals, payments, and 50+ other data categories across Accounting, Payroll, and Projects |
| **Xero Reports** | Pulls pre-built financial reports — Profit and Loss, Balance Sheet, Trial Balance, Budget Summary, Bank Statement, and 4 others |
## Why connect Xero to Coupler.io?
* **Automate financial reporting** — Schedule regular data refreshes so your spreadsheets and dashboards always reflect the latest accounting data.
* **Build custom dashboards** — Export P\&L, Balance Sheet, or transaction data to Looker Studio, Power BI, or Google Sheets for visualization beyond what Xero offers natively.
* **Combine with other sources** — Merge Xero data with CRM, e-commerce, or advertising data for a full picture of business performance.
* **Flexible destinations** — Export to AI tools, Google Sheets, Excel, BigQuery, Looker Studio, Power BI, or other supported destinations.
## Prerequisites
Before connecting, make sure you have:
* A **Xero** account with access to the organization you want to pull data from
* Standard or Advisor-level access to the Xero organization
* A Coupler.io account
{% hint style="warning" %}
If you have access to multiple Xero organizations (tenants), you'll select which one to pull data from during setup. If you add a new tenant later, you'll need to reconnect your Xero account in Coupler.io for it to appear.
{% endhint %}
## Quick start
{% hint style="success" %}
Start with a **Profit And Loss** report using the **Date-by-row format**, with **End date** set to `2025-12-31` and **Start date** to `2025-01-01`, **Number of periods to compare** = 11, and **Period** = Month. This gives you a monthly P\&L for the current year. Run it once to verify the connection, then set up a daily or weekly auto-refresh — and update the dates each year.
{% endhint %}
## How to connect
Both Xero data sources use **OAuth authentication** — you sign in with your Xero account directly.
{% stepper %}
{% step %}
In Coupler.io, create a new **data flow** and select **Xero** (for entity data) or **Xero Reports** (for financial reports) as the source.
{% endstep %}
{% step %}
Click **Connect** and sign in with your Xero account.\
Grant Coupler.io permission to **view your Xero data** and click **Allow access**.
{% endstep %}
{% step %}
Select the **Xero tenant** (organization) you want to pull data from.
{% endstep %}
{% step %}
**For Xero (entities):** Select a **data entity** (e.g., Invoices, Contacts, Bank Transactions). Optionally choose a **Report type** (Simple or Detailed) and configure **Where**, **Order by**, and **Split by** parameters.
{% endstep %}
{% step %}
**For Xero Reports:** Select a **report type** (e.g., Profit And Loss, Balance Sheet). Choose a **Report structure** (Xero-style or Date-by-row format). Set the **report period**.
{% endstep %}
{% step %}
Choose your **destination** and run the import.
{% endstep %}
{% endstepper %}
## Xero data overview
Coupler.io provides two separate Xero data sources, each designed for different use cases. **Xero** gives you raw entity data (invoices, contacts, journals, etc.), while **Xero Reports** gives you pre-built financial reports (P\&L, Balance Sheet, Trial Balance, etc.).
## Xero (Entity Data)
This source pulls structured records directly from your Xero organization. Select one entity per data flow. Entities are organized into four groups.
#### Accounting entities
| Entity | Description | Typical use case |
| --------------------- | --------------------------------- | ------------------------------------- |
| **Invoices** | Customer invoices with line items | Revenue tracking, accounts receivable |
| **Contacts** | Customers and suppliers | Contact management, CRM sync |
| **Bank Transactions** | Reconciled bank transactions | Cash flow tracking, reconciliation |
| **Payments** | Payment records | Payment tracking, collections |
| **Credit Notes** | Credit notes issued | Refund and credit tracking |
| **Journals** | System-generated journal entries | Audit trails, GL analysis |
| **Manual Journals** | User-created journal entries | Adjustments, accruals |
| **Accounts** | Chart of accounts | Account structure, reporting |
| **Items** | Products and services | Inventory, catalog management |
| **Purchase Orders** | Purchase orders | Procurement tracking |
| **Quotes** | Quotes and estimates | Sales pipeline |
| **Expense Claims** | Employee expense claims | Expense management |
| **Receipts** | Receipts | Expense tracking |
Additional Accounting entities: Bank Transfers, Branding Themes, Contact Groups, Currencies, Employees, Linked Transactions, Organisation, Overpayments, Prepayments, Repeating Invoices, Tax Rates, Tracking Categories, Users.
#### Payroll entities (UK/NZ)
| Entity | Description |
| ------------------------ | ---------------------------------- |
| **Employees (UK or NZ)** | Employee records for UK/NZ payroll |
| **Pay Runs** | Pay run records |
| **Timesheets** | Employee timesheets |
| **Benefits** | Employee benefits |
| **Deductions** | Payroll deductions |
| **Earning Rates** | Earning rate definitions |
| **Leave Types** | Leave type definitions |
Additional UK/NZ entities: Earnings Orders (Statutory deductions), Pay Run Calendars, Reimbursements, Accounts (UK or NZ), Tracking Categories (UK or NZ).
#### Payroll entities (Australia)
| Entity | Description |
| ---------------------- | --------------------------------------- |
| **Employees (AU)** | Employee records for Australian payroll |
| **Pay Runs** | Pay run records |
| **Leave Applications** | Leave requests and approvals |
| **Timesheets** | Employee timesheets |
| **Super Funds** | Superannuation fund records |
| **Payroll Calendars** | Payroll schedule definitions |
Additional AU entities: Earnings Rates, Deduction Types, Leave Types, Reimbursement Types, Settings, Accounts (AU), Tracking Categories (AU), Leave Applications with Leave Periods, Timesheets with Timesheet Lines.
#### Project entities
| Entity | Description |
| --------------------- | --------------------------------------- |
| **Projects** | Project records with status and budgets |
| **Tasks by Projects** | Tasks within projects |
| **Time by Projects** | Time entries logged against projects |
| **Users** | Project team members |
#### Entity parameters
| Parameter | Purpose | Example |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| **Report type** | Simple (default fields) or Detailed (extended fields) — available for Invoices, Contacts, Bank Transactions, Credit Notes, Manual Journals, Overpayments, Prepayments | `Detailed` |
| **Where** | Filter records using Xero query syntax | `Type=="ACCREC" AND Status=="AUTHORISED"` |
| **Order by** | Sort results ascending or descending | `EmailAddress DESC` |
| **Split by** | Split nested values (e.g., line items) into separate rows | `LineItems` |
| **Changed after** | Export only records updated after a date | `2025-02-22` |
| **Include archived** | Include archived invoices, contacts, or tracking categories | Toggle on |
{% hint style="info" %}
The Where parameter uses Xero's own query syntax, which differs from QuickBooks. Dates must use the `DateTime(YYYY, MM, DD)` format, strings use `==` with double quotes, and GUIDs use `=GUID("value")`. See the [Where parameter guide](/sources/category/finance-and-accounting/xero/how-to-use-where-filter-in-xero.md) for full syntax and per-entity examples.
{% endhint %}
## Xero Reports (Financial Reports)
This source pulls formatted financial reports from your Xero organization. Each report has its own parameters.
#### Available reports
| Report | What it shows | Key parameters |
| ------------------------------- | -------------------------------------------- | ------------------------------------------------------------ |
| **Profit And Loss** | Revenue and expenses over a period | Start/End date, Periods, Tracking Category ID, Payments only |
| **Balance Sheet** | Assets, liabilities, and equity snapshot | Date, Periods, Tracking Option ID, Payments only |
| **Trial Balance** | Debit/credit balances for all accounts | Date, Payments only |
| **Budget Summary** | Monthly budget summary | Date, Periods |
| **Executive Summary** | Monthly totals and business ratios | Date |
| **Bank Summary** | Balances and cash movements per bank account | Start/End date |
| **Bank Statement** | Transactions for a specific bank account | Bank Account ID, Start/End date |
| **Aged Payables By Contact** | Outstanding bills for a specific contact | Contact ID, Date, Start/End date |
| **Aged Receivables By Contact** | Outstanding invoices for a specific contact | Contact ID, Date, Start/End date |
#### Report configuration options
| Option | Purpose | Available for |
| ---------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------ |
| **Report structure** | Xero-style format (dates as columns) or Date-by-row format (dates in rows) | P\&L, Balance Sheet, Budget Summary, Executive Summary |
| **Number of periods to compare** | Add previous periods for comparison (up to 11 or 12) | P\&L, Balance Sheet, Budget Summary |
| **Period** | Group by Month, Quarter, or Year | P\&L, Balance Sheet, Budget Summary |
| **Tracking Category ID** | Filter P\&L by tracking category (each option becomes a column) | Profit And Loss |
| **Tracking Option ID** | Filter by a specific tracking option | Balance Sheet, Profit And Loss |
| **Include cash transactions only** | Show only cash-basis transactions | P\&L, Balance Sheet, Trial Balance |
## Common data combinations
| Goal | Source | Configuration |
| ------------------------- | ------------ | -------------------------------------------------------------------------------------------- |
| Monthly P\&L dashboard | Xero Reports | Profit And Loss, Date-by-row, 11 periods, Month |
| Accounts receivable aging | Xero Reports | Aged Receivables By Contact with Contact ID |
| Invoice line-item export | Xero | Invoices entity, Report type = Detailed, Split by = `LineItems` |
| Bank reconciliation | Xero | Bank Transactions entity with date filters |
| Budget vs. actual | Xero Reports | Budget Summary + Profit And Loss (separate flows) |
| Year-over-year P\&L | Xero Reports | Two P\&L flows: one for this year (e.g., `2025-01-01` to `2025-12-31`) and one for last year |
## Use cases by role
{% tabs %}
{% tab title="Finance / Accounting" %}
Automate P\&L, Balance Sheet, and Trial Balance exports to Google Sheets or BigQuery. Use tracking categories to break down reports by region, department, or cost center. Use the Date-by-row report structure for trend analysis and combine multiple periods for month-over-month comparisons.
{% endtab %}
{% tab title="Business Owners" %}
Build monthly revenue and expense dashboards in Looker Studio or Power BI without waiting for accountant reports. Start with Profit And Loss by Month and Bank Summary for a real-time snapshot of your business health.
{% endtab %}
{% tab title="Bookkeepers / Advisors" %}
Export journals, bank transactions, and invoices for audit preparation and reconciliation. Use the Detailed report type for invoices and Split by = `LineItems` to get line-level detail. Combine data from multiple Xero tenants by creating separate data flows per organization.
{% endtab %}
{% tab title="Operations" %}
Track purchase orders, expense claims, and project time entries. Use Projects entities to monitor project budgets and billable hours. Combine with invoice data for end-to-end project profitability analysis.
{% endtab %}
{% endtabs %}
## Platform-specific notes
* **Multi-tenant support** — If you have access to multiple Xero organizations, select the tenant during setup. Each data flow pulls from one tenant. To consolidate data across organizations, create separate data flows and combine in your destination.
* **P\&L End Date limitation** — Xero's API treats the End Date as the cutoff day for every month in the report. If you use a month with only 30 days (e.g., September 30), you'll lose one day of data from months with 31 days. Always use a month with 31 days as End Date (e.g., 12-31, 10-31, 08-31, 07-31).
* **Bank Transactions** — The Bank Transactions entity pulls reconciled transactions only. Unreconciled transactions are not available via the API.
* **Journals vs. Manual Journals** — Journals are system-generated (from invoices, payments, etc.) and don't support the Where parameter — use the Journal number filters instead. Manual Journals are user-created and do support Where filtering.
* **Tracking categories** — To filter reports by tracking category, you need the category ID and optionally the option ID. Export the Tracking Categories entity with Split by = `Options` to get all IDs.
* **Aged reports require a Contact ID** — The Aged Payables and Aged Receivables reports only return data for one contact at a time. There is no "all contacts" option. To get aging data for all contacts, you would need to create a separate data flow per contact or use the Invoices entity with status filters as an alternative.
* **Date fields** — Report date fields use the date picker. The Xero Where parameter requires the `DateTime(YYYY, MM, DD)` format — for example: `Date >= DateTime(2025, 01, 01)`.
## Xero common issues
### Connection Issues
OAuth token expired — reconnection required
Xero OAuth tokens can expire or be revoked if your Xero credentials change, if you remove the Coupler.io app from your Xero account, or after prolonged inactivity.
**Fix:**
1. Go to your Coupler.io data flow settings.
2. Click the source connection and select **Reconnect**.
3. Sign in again with your Xero credentials and re-authorize.
If the Reconnect option doesn't appear, remove the existing Xero connection from **Settings → Connections** and create a new one.
403 Forbidden error
This means the connected Xero account doesn't have sufficient permissions for the requested entity or tenant.
**Fix:**
1. Verify the connected account has Standard or Advisor access to the Xero organization.
2. Check that the correct **tenant** is selected in the data flow settings.
3. For Payroll entities, ensure the account has Payroll Admin access.
4. Reconnect if your permissions were recently updated — Coupler.io captures permissions at connection time.
New tenant not appearing in the dropdown
Coupler.io captures available tenants when the Xero connection is first created. If you add a new Xero organization after connecting, it won't appear automatically.
**Fix:** Go to **Settings → Connections**, remove the existing Xero connection, and create a new one. The new tenant will be available in the dropdown.
### Missing Data
Bank Transactions only shows reconciled data
The Xero Bank Transactions entity pulls only reconciled transactions. Unreconciled bank feed items are not accessible via the Xero API.
**Fix:** There is no workaround — this is a Xero API limitation. Ensure your bank transactions are reconciled in Xero before pulling data. Alternatively, use the Bank Statement report for a broader view of bank activity.
Invoice or journal data is missing line-item detail
When exporting invoices, credit notes, journals, or other entities with nested line items, each record appears as a single row with aggregated or concatenated data.
**Fix:** Set the **Split by** parameter to `LineItems` (for invoices, credit notes, bank transactions) or `JournalLines` (for journals). This splits multi-line documents into separate rows — one row per line item.
Detailed report type not available for my entity
The Detailed report type is only supported for Invoices, Contacts, Bank Transactions, Credit Notes, Manual Journals, Overpayments, and Prepayments. All other entities only support the Simple report type.
**Fix:** If your entity doesn't support Detailed, use Simple and supplement with the **Split by** parameter if you need nested data expanded.
Account Transactions report is not available
The "Account Transactions" report that exists in the Xero UI is not available through Xero's API. This is one of the most common feature requests (11+ tickets).
**Fix:** As a workaround, use the **Journals** entity (for system-generated entries) or **Manual Journals** entity and filter by account. You can also combine the Invoices, Payments, and Bank Transactions entities to reconstruct transactional detail for specific accounts.
### Data Discrepancies
P&L report shows incorrect values for some months
Xero's API treats the End Date as the cutoff day for **every month** in the report. If you set the End Date to a month with only 30 days (e.g., September 30), all months in the report will only include data up to the 30th — losing one day from months with 31 days.
**Fix:** Always use an End Date in a month with 31 days:
* 12-31, 10-31, 08-31, 07-31, 05-31, 03-31, or 01-31
If the current month doesn't have 31 days, use the next month that does. For example, to get a P\&L through June, set the End Date to July 31.
{% hint style="danger" %}
The P\&L End Date issue is a Xero API limitation, not a Coupler.io limitation. This is the single most common Xero support question (14 tickets). Always use a 31-day month as your End Date (e.g., `2025-12-31`) to avoid this issue entirely for year-end reports.
{% endhint %}
Report totals don't match Xero UI
Small differences between Coupler.io exports and the Xero UI can occur when the report covers a different date range, includes/excludes cash-only transactions, or uses different tracking category filters.
**Fix:**
1. Confirm the **date range** matches exactly.
2. Check the **Include cash transactions only** toggle.
3. Verify **Tracking Category ID** and **Tracking Option ID** parameters match your Xero filter settings.
4. For Balance Sheet, note that the report shows data as of the **end of the month** regardless of the specific day selected.
Aged Payables/Receivables only shows one contact
The Aged Payables By Contact and Aged Receivables By Contact reports require a **Contact ID** parameter. They return data for only one contact per data flow. There is no "all contacts" option in the Xero API.
**Fix:** If you need aging data for all contacts:
1. Use the **Invoices** entity with status filters (AUTHORISED, for outstanding) as an alternative.
2. For a full aged report, you would need to create a separate data flow per contact — impractical for large contact lists.
3. Consider using the Purchase Orders or Invoice entities with date-based Where filters to approximate aging buckets.
### Rate Limits and API Errors
Xero API rate limit exceeded
Xero enforces API rate limits. If you have multiple data flows running simultaneously against the same Xero organization, you may hit rate limits causing temporary failures.
**Fix:**
* Stagger your data flow schedules so they don't all run at the same time.
* Reduce the frequency of data refreshes if you have many Xero data flows.
* Use the **Changed after** parameter to pull only recently modified records, reducing API calls.
Timeout error on large datasets
Data flows that pull very large volumes (e.g., thousands of journals or invoices) may time out, especially when using the Detailed report type or Split by parameter.
**Fix:**
* Use the **Changed after** parameter to limit the date range and reduce data volume.
* For Journals, use the **Journal number more than** / **Journal number less than** parameters to pull in batches.
* Switch from Detailed to Simple report type if you don't need the extended fields.
Data type mismatch errors when exporting to BigQuery
BigQuery requires consistent data types within a column. If Xero returns mixed types in a column, the import may fail.
**Fix:** Use a transformation step in Coupler.io to standardize data types before export, or exclude problematic columns using the column selector.
## Xero FAQ
What's the difference between Xero and Xero Reports in Coupler.io?
**Xero** pulls raw entity data — individual records like invoices, contacts, bank transactions, journals, and 50+ other data categories across Accounting, Payroll, and Projects. Each record is a row with all its fields.
**Xero Reports** pulls pre-built financial reports — Profit And Loss, Balance Sheet, Trial Balance, Budget Summary, and 5 others. These are the same reports you see in Xero, formatted with totals, subtotals, and groupings.
Use **Xero** when you need granular transactional data. Use **Xero Reports** when you need summarized financial data for dashboards or analysis.
Can I pull custom reports from Xero?
No. Coupler.io can only pull the 9 predefined report types available through the Xero API (Profit And Loss, Balance Sheet, Trial Balance, Budget Summary, Executive Summary, Bank Summary, Bank Statement, Aged Payables By Contact, Aged Receivables By Contact). Custom reports created inside the Xero UI are not accessible via the API.
As a workaround, use the closest predefined report and apply parameters (tracking categories, date ranges, cash-only toggle) to approximate your custom report. For transactional detail, use the entity data source with Where filters.
Is the Account Transactions report available?
No. The "Account Transactions" report in the Xero UI is not available through the Xero API. This is a native report built on top of the General Ledger and does not have an API endpoint.
As a workaround, use the **Journals** entity to get system-generated journal entries, or combine Invoices, Payments, and Bank Transactions entities to reconstruct transactional detail for specific accounts. You can filter by account using the Where parameter.
Why is my P&L missing data for some months?
Xero's API treats the End Date as the cutoff day for **every month** in the report. If your End Date falls in a month with only 30 days (e.g., September 30), all months will be truncated to the 30th — losing one day from 31-day months.
Always use an End Date in a month with 31 days: 12-31, 10-31, 08-31, 07-31, 05-31, 03-31, or 01-31. For example, use `2025-12-31` as the End Date for a full-year report.
How do I set up a dynamic monthly P&L that updates automatically?
Set the report date parameters as follows:
* **Start Date:** `2025-01-01`
* **End Date:** `2025-12-31`
* **Number of periods to compare:** 11
* **Period:** Month
This generates a full-year monthly P\&L. For year-over-year comparisons, duplicate the data flow and set the dates to the previous year (e.g., `2024-01-01` / `2024-12-31`). Update the dates at the start of each new year.
How do I filter reports by tracking category?
You need the Tracking Category ID (a GUID), not the category name. To find it:
1. Create a data flow using the **Xero** source with the **Tracking Categories** entity.
2. Set **Report type** to Simple and **Split by** to `Options`.
3. Run the flow — this exports all tracking categories and their option IDs.
4. Copy the Tracking Category ID and paste it into the **Tracking Category ID** parameter in your Xero Reports data flow.
To filter by a specific option within the category, also set the **Tracking Option ID** parameter. You can use up to two tracking categories simultaneously on P\&L reports.
Can I get Aged Payables or Aged Receivables for all contacts at once?
No. The Aged Payables By Contact and Aged Receivables By Contact reports require a **Contact ID** — they only return data for one contact per data flow. The Xero API does not provide an "all contacts" aging report.
For a full aging overview, consider using the **Invoices** entity with status filters (e.g., `Status=="AUTHORISED"`) and date-based Where filters to approximate aging buckets across all contacts.
How do I export invoice line items as separate rows?
Set the **Split by** parameter to `LineItems` in your data flow settings. This tells Coupler.io to split invoices into separate rows — one row per line item.
This works for Invoices, Credit Notes, Bank Transactions, Purchase Orders, Quotes, and other entities with nested line items. For Journals, use `JournalLines` instead.
How do I use the Where parameter to filter by date?
Xero's Where parameter requires dates in `DateTime(YYYY, MM, DD)` format, not ISO dates. Examples:
* `Date >= DateTime(2025, 01, 01)` — records from January 1, 2025 onward
* `Date >= DateTime(2025, 01, 01) AND Date < DateTime(2025, 02, 01)` — January 2025 only
Use `AND` / `&&` to combine conditions and `OR` / `||` for alternative conditions. See the full [Where parameter guide](/sources/category/finance-and-accounting/xero/how-to-use-where-filter-in-xero.md).
What's the difference between Simple and Detailed report types?
**Simple** returns the default fields for an entity — suitable for basic exports and smaller datasets.
**Detailed** returns an extended list of fields with more granular information — suitable for comprehensive analysis. Detailed is only available for: Invoices, Contacts, Bank Transactions, Credit Notes, Manual Journals, Overpayments, and Prepayments.
For all other entities, only Simple is available.
How do I handle multiple Xero organizations (tenants)?
Each data flow pulls from one Xero tenant. To consolidate data across multiple organizations:
1. Create separate data flows for each tenant.
2. Export all flows to the same destination (e.g., same BigQuery dataset or Google Sheet).
3. Add a formula column or label to identify which tenant the data comes from.
4. Use Coupler.io's Append transformation to combine the datasets.
If you add a new tenant to your Xero account, you'll need to reconnect your Xero account in Coupler.io for the new tenant to appear.
What report structure should I choose — Xero-style or Date-by-row?
**Xero-style format** displays dates as column headers (like `31 Jan 25`, `28 Feb 25`), mirroring the Xero UI. This is familiar but hard to analyze in BI tools because each month is a separate column.
**Date-by-row format** puts dates in a single column, with one row per date-account combination. This is much easier to filter, pivot, and chart in Google Sheets, Looker Studio, or Power BI.
Use **Date-by-row** for analytics and dashboards. Use **Xero-style** when you want the export to look like the Xero report for presentation purposes.
{% hint style="info" %}
For detailed Where parameter syntax and per-entity field references, see the [Where parameter guide](/sources/category/finance-and-accounting/xero/how-to-use-where-filter-in-xero.md). For report-specific parameters, see the [Xero Reports parameters guide](/sources/category/finance-and-accounting/xero/how-to-use-advanced-settings-in-xero-source.md). For dynamic P\&L setup with macros, see the [Monthly P\&L setup](#quick-start).
{% endhint %}
---
# 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/finance-and-accounting/xero.md?ask=&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.