> 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/ppc/chatgpt-ads.md).
# ChatGPT Ads
Connect ChatGPT Ads to Coupler.io to export campaign, ad group, ad, country, and conversion performance — setup, data reference, troubleshooting, and FAQ in one place.
ChatGPT Ads is OpenAI's advertising platform, managed through [Ads Manager](https://ads.openai.com/). It serves ads inside ChatGPT and reports the familiar delivery metrics — impressions, clicks, spend, CTR, CPC, CPM — plus conversions when you have conversion tracking set up.
Connecting ChatGPT Ads to Coupler.io pulls that reporting into your own spreadsheets, warehouse, or BI tool on a schedule, so you can track this channel next to the rest of your paid media instead of exporting from Ads Manager by hand.
**Why connect ChatGPT Ads to Coupler.io?**
* Report on ChatGPT Ads alongside Google Ads, Facebook Ads, LinkedIn Ads, and other channels in one blended dataset
* Pick the reporting grain you need — account, campaign, ad group, ad, or campaign-by-country
* Track conversions separately, split into click-through and view-through
* Export to AI tools, Google Sheets, Excel, BigQuery, Data Studio, or other supported destinations
* Keep reports current with scheduled refreshes instead of manual CSV downloads
## Prerequisites
Before you start, make sure you have:
* A ChatGPT Ads account with at least one ad account
* An API key generated in the **Settings** tab of [Ads Manager](https://ads.openai.com/settings)
{% hint style="warning" %}
**Each API key is scoped to one ad account.** If you manage several ad accounts, generate a key per account, create separate connection in Coupler.io, use each connection in it's own source and [Append](/functionality/preview-data/combining-data/append-data.md) sources data on Data sets step.
{% endhint %}
## Quick start
{% hint style="success" %}
Start with **Campaign performance** at **Daily** granularity. It's the grain most reports are built on, and the daily split is what makes scheduled runs fetch only new days instead of re-pulling the whole range.
{% endhint %}
## How to connect
{% stepper %}
{% step %}
**Generate your API key.** Open [Ads Manager settings](https://ads.openai.com/settings) and create an API key. The key is shown only once, so copy it right away. It grants full Ads Management API access — store it securely.
{% endstep %}
{% step %}
**Create a new data flow in Coupler.io.** Search for and select **ChatGPT Ads** as your source.
{% endstep %}
{% step %}
**Click Connect.** Optionally, share the account with your team. Then enter an account name that identifies the ad account, so you can tell later which account the key belongs to, and paste the key into the **API key** field. Coupler.io reads the ad account the key is scoped to, so there is no separate account picker.
{% endstep %}
{% step %}
**Choose a report type.** Select one of the six options in **Report type** — for example, **Campaign performance**. Each report type is a different grain; see [Data Overview](#data-overview) for what each one returns.
{% endstep %}
{% step %}
**Set the report period and granularity.** Use the date pickers to set the start and end dates, then set **Split data by period** to Daily, Monthly, or Totals only.
{% endstep %}
{% step %}
**Choose a destination.** Select where the data should land — Google Sheets, Excel, BigQuery, Data Studio, or an AI destination like ChatGPT, Claude, or Gemini.
{% endstep %}
{% step %}
**Run the data flow.** Click **Run** for a manual sync, then set a schedule so the report refreshes on its own.
{% endstep %}
{% endstepper %}
## Configuration options
### Report type
| Report type | What it contains |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Ad account performance | Account-level totals — impressions, clicks, spend, CTR, CPC, CPM, plus account budgets. One row per period |
| Campaign performance | One row per campaign per period, with campaign status, schedule, budgets, and delivery metrics |
| Ad group performance | One row per ad group per period, with its parent campaign for context |
| Ad performance | One row per ad per period, including ad title, copy, destination link, and review status |
| Campaign performance by country | One row per campaign, country, and period — the country of the person who saw the ad |
| Campaign conversions | Conversions per campaign per period, split into click-through and view-through. Requires conversion tracking |
See [Data overview](#data-overview) to check which fields and metrics each report type returns.
{% hint style="info" %}
Need more than one report type? Add each as a separate source within the **same** data flow rather than building several flows, and keep each report type as its own table or sheet in the destination.
{% endhint %}
### Report period
Set **Start date** and **End date** with the date pickers. A couple of things to know:
* The API reads your dates on the **ad account's own clock**, not UTC. The `timezone` field in every report tells you which one that is.
* An end date in the future makes the run fail. Keep the end date at today or earlier.
### Split data by period
| Option | What you get | Available for |
| ----------- | ------------------------------------------------------ | ------------------------------- |
| Daily | One row per entity per day, with a date column | All report types |
| Monthly | One row per entity per month, with a date column | All except Campaign conversions |
| Totals only | One row per entity for the whole range, no date column | All report types |
{% hint style="warning" %}
**Campaign conversions does not support Monthly yet.** For this report type, Coupler.io currently offers only Daily and Totals only. If you need monthly conversion totals, pull Daily and aggregate in the dataset step. To request Monthly support, post on [feedback.coupler.io](https://feedback.coupler.io).
{% endhint %}
Two behaviors worth knowing before you choose:
* **Monthly dates are labeled with the first of the month.** A July 2026 bucket arrives as `2026-07-01`, not `2026-07`. The month is also aligned to the calendar — picking a start date of July 10 with Monthly granularity gives you a bucket covering all of July, not July 10 onward.
* **Totals only re-fetches the entire range on every run.** Daily and Monthly let Coupler.io sync incrementally; Totals only cannot, because there's no date column to sync against.
## Data Overview
ChatGPT Ads in Coupler.io is organized as six report types. You pick one per source, set a date range, and choose how the data is bucketed by time. Everything else — fields, grain, row count — follows from the report type you pick.
### Field reference
Each report type returns the fields listed below. **Report: Date** is present on Daily and Monthly splits and absent on Totals only. **Account: Account Id** and **Account: Account URL** are hidden by default in the dataset step — unhide them if you need them. Account fields in Campaign conversions are the account name, ID, and URL only.
{% hint style="danger" %}
**CTR, CPC, and CPM are ratios and must never be summed or averaged across rows.** Summing a day's CPC values gives a meaningless number, and averaging them weights a day with 2 clicks the same as a day with 2,000. Always recalculate at your aggregation level from the raw totals: `CTR = SUM(clicks) / SUM(impressions)`, `CPC = SUM(spend) / SUM(clicks)`, `CPM = SUM(spend) / SUM(impressions) * 1000`. Impressions, clicks, spend, and the conversion counts are summable.
{% endhint %}
#### Ad account performance
| Field | Description |
| ------------------------ | ---------------------------------------------------------------------- |
| Report: Date | Date bucket for the row |
| Account: Account name | Name of the ad account |
| Account: Account Id | Unique ad account identifier |
| Account: Account URL | Website associated with the ad account |
| Account: Timezone | Timezone the account reports in — the clock your date range is read on |
| Account: Daily budget | Account-level daily budget cap |
| Account: Lifetime budget | Account-level lifetime budget cap |
| Performance: Impressions | Times the ad was shown |
| Performance: Clicks | Clicks on the ad |
| Cost: Amount spend | Spend for the row |
| Clicks: CTR | Clicks ÷ impressions (ratio) |
| Cost: CPC | Spend ÷ clicks (ratio) |
| Cost: CPM | Cost per thousand impressions (ratio) |
#### Campaign performance
| Field | Description |
| ------------------------------ | -------------------------------------- |
| Report: Date | Date bucket for the row |
| Account: Account name | Name of the ad account |
| Account: Account Id | Unique ad account identifier |
| Account: Account URL | Website associated with the ad account |
| Account: Timezone | Timezone the account reports in |
| Campaign: Campaign Id | Unique campaign identifier |
| Campaign: Campaign name | Campaign name as set in Ads Manager |
| Campaign: Campaign description | Free-text campaign description |
| Campaign: Campaign status | Delivery status, e.g. `active` |
| Campaign: Start date | Scheduled campaign start |
| Campaign: End date | Scheduled campaign end |
| Campaign: Daily budget | Daily budget cap |
| Campaign: Lifetime budget | Lifetime budget cap |
| Performance: Impressions | Times the ad was shown |
| Performance: Clicks | Clicks on the ad |
| Cost: Amount spend | Spend for the row |
| Clicks: CTR | Clicks ÷ impressions (ratio) |
| Cost: CPC | Spend ÷ clicks (ratio) |
| Cost: CPM | Cost per thousand impressions (ratio) |
#### Ad group performance
| Field | Description |
| ------------------------------ | -------------------------------------- |
| Report: Date | Date bucket for the row |
| Account: Account name | Name of the ad account |
| Account: Account Id | Unique ad account identifier |
| Account: Account URL | Website associated with the ad account |
| Account: Timezone | Timezone the account reports in |
| Campaign: Campaign Id | Unique campaign identifier |
| Campaign: Campaign name | Campaign name as set in Ads Manager |
| Campaign: Campaign description | Free-text campaign description |
| Campaign: Campaign status | Delivery status, e.g. `active` |
| Campaign: Start date | Scheduled campaign start |
| Campaign: End date | Scheduled campaign end |
| Campaign: Daily budget | Daily budget cap |
| Campaign: Lifetime budget | Lifetime budget cap |
| Ad group: Ad group Id | Unique ad group identifier |
| Ad group: Ad group name | Ad group name |
| Ad group: Ad group description | Free-text ad group description |
| Ad group: Ad group status | Ad group delivery status |
| Performance: Impressions | Times the ad was shown |
| Performance: Clicks | Clicks on the ad |
| Cost: Amount spend | Spend for the row |
| Clicks: CTR | Clicks ÷ impressions (ratio) |
| Cost: CPC | Spend ÷ clicks (ratio) |
| Cost: CPM | Cost per thousand impressions (ratio) |
#### Ad performance
| Field | Description |
| ------------------------------ | -------------------------------------- |
| Report: Date | Date bucket for the row |
| Account: Account name | Name of the ad account |
| Account: Account Id | Unique ad account identifier |
| Account: Account URL | Website associated with the ad account |
| Account: Timezone | Timezone the account reports in |
| Campaign: Campaign Id | Unique campaign identifier |
| Campaign: Campaign name | Campaign name as set in Ads Manager |
| Campaign: Campaign description | Free-text campaign description |
| Campaign: Campaign status | Delivery status, e.g. `active` |
| Campaign: Start date | Scheduled campaign start |
| Campaign: End date | Scheduled campaign end |
| Campaign: Daily budget | Daily budget cap |
| Campaign: Lifetime budget | Lifetime budget cap |
| Ad group: Ad group Id | Unique ad group identifier |
| Ad group: Ad group name | Ad group name |
| Ad group: Ad group description | Free-text ad group description |
| Ad group: Ad group status | Ad group delivery status |
| Ad: Ad Id | Unique ad identifier |
| Ad: Ad name | Internal ad name |
| Ad: Ad title | Headline shown to users |
| Ad: Ad copy | Body copy shown to users |
| Ad: Ad link | Destination URL |
| Ad: Ad status | Ad delivery status |
| Ad: Ad review status | Where the ad stands in policy review |
| Performance: Impressions | Times the ad was shown |
| Performance: Clicks | Clicks on the ad |
| Cost: Amount spend | Spend for the row |
| Clicks: CTR | Clicks ÷ impressions (ratio) |
| Cost: CPC | Spend ÷ clicks (ratio) |
| Cost: CPM | Cost per thousand impressions (ratio) |
#### Campaign performance by country
| Field | Description |
| ------------------------------ | -------------------------------------------------------------------- |
| Report: Date | Date bucket for the row |
| Account: Account name | Name of the ad account |
| Account: Account Id | Unique ad account identifier |
| Account: Account URL | Website associated with the ad account |
| Account: Timezone | Timezone the account reports in |
| Campaign: Campaign Id | Unique campaign identifier |
| Campaign: Campaign name | Campaign name as set in Ads Manager |
| Campaign: Campaign description | Free-text campaign description |
| Campaign: Campaign status | Delivery status, e.g. `active` |
| Campaign: Start date | Scheduled campaign start |
| Campaign: End date | Scheduled campaign end |
| Campaign: Daily budget | Daily budget cap |
| Campaign: Lifetime budget | Lifetime budget cap |
| Audience: Country | Country of the person who saw the ad, shown as the full country name |
| Performance: Impressions | Impressions in this country |
| Performance: Clicks | Clicks in this country |
| Cost: Amount spend | Spend in this country |
| Clicks: CTR | Clicks ÷ impressions (ratio) |
| Cost: CPC | Spend ÷ clicks (ratio) |
| Cost: CPM | Cost per thousand impressions (ratio) |
| Campaign: Total impressions | Campaign total for the period — **repeated on every country row** |
| Campaign: Total clicks | Campaign total for the period — repeated on every country row |
| Campaign: Total spend | Campaign total for the period — repeated on every country row |
| Campaign: Total CTR | Campaign total for the period — repeated on every country row |
| Campaign: Total CPC | Campaign total for the period — repeated on every country row |
| Campaign: Total CPM | Campaign total for the period — repeated on every country row |
{% hint style="danger" %}
**Do not sum the `Campaign: Total …` fields in the by-country report.** They carry the campaign's total for the whole period, duplicated onto each country row. A campaign that ran in 12 countries will have its total spend repeated 12 times — summing it multiplies your spend by 12. Sum the plain `Performance:` and `Cost:` fields for country-level numbers; use the `Campaign: Total …` fields only as a per-row denominator, for example to work out each country's share of a campaign.
{% endhint %}
#### Campaign conversions
| Field | Description |
| -------------------------------------- | ------------------------------------------------ |
| Report: Date | Date bucket for the row |
| Account: Account name | Name of the ad account |
| Account: Account Id | Unique ad account identifier |
| Account: Account URL | Website associated with the ad account |
| Campaign: Campaign Id | Unique campaign identifier |
| Campaign: Campaign name | Campaign name as set in Ads Manager |
| Conversions: Conversions | Total conversions attributed to the campaign |
| Conversions: Click-through conversions | Conversions where the user clicked the ad |
| Conversions: View-through conversions | Conversions where the user saw but did not click |
{% hint style="info" %}
The conversions report covers **every campaign in the account**, including campaigns with zero conversions in the period. Those arrive as rows of zeros rather than being omitted — which means row count tracks your campaign count, not your conversion volume.
{% endhint %}
### Common field combinations
| Goal | Report type | Split data by period | Fields to use |
| -------------------------------------- | ------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Spot creative fatigue over time | Ad performance | Daily | `Performance: Impressions`, `Performance: Clicks`, and CTR recalculated from them, by `Ad: Ad name` and `Report: Date` |
| Cost per conversion by campaign | Campaign performance and Campaign conversions, as two sources | Daily | `Cost: Amount spend` and `Conversions: Conversions`, matched on campaign ID and date downstream |
| Budget pacing by campaign | Campaign performance | Daily | `Cost: Amount spend` against `Campaign: Daily budget` and `Campaign: Lifetime budget`, by `Campaign: Campaign name` and `Report: Date` |
| Budget pacing for the whole account | Ad account performance | Daily | `Cost: Amount spend` against `Account: Daily budget` and `Account: Lifetime budget` |
| Each country's share of campaign spend | Campaign performance by country | Totals only or Daily | `Cost: Amount spend` divided by `Campaign: Total spend` on the same row |
| Ads stuck in review | Ad performance | Totals only | `Ad: Ad status` and `Ad: Ad review status`, filtered to non-approved |
### Use cases by role
{% tabs %}
{% tab title="Marketers" %}
* Pull Campaign performance daily into Google Sheets and build a live ChatGPT Ads dashboard in Data Studio
* Append ChatGPT Ads with Google Ads and Facebook Ads in one data flow for a single cross-channel spend table
* Watch `Ad: Ad review status` to spot creatives held up in policy review before they cost you delivery days
* Send campaign performance to ChatGPT or Claude for a written weekly summary
{% endtab %}
{% tab title="Performance analysts" %}
* Load Campaign performance and Campaign conversions as separate tables and match them on campaign ID and date downstream to calculate true cost per conversion
* Compare click-through against view-through conversions to judge how much credit view-through attribution is taking
* Use Campaign performance by country to find geographies that underperform the campaign average
* Use Ad performance at Daily granularity to measure creative decay across a flight
{% endtab %}
{% tab title="Finance and ops" %}
* Pull Ad account performance at Monthly granularity for a clean spend-by-month table to reconcile against invoices
* Track spend against `Account: Daily budget` and `Account: Lifetime budget` for pacing alerts
* Load account totals into BigQuery alongside other channels for consolidated media spend reporting
{% endtab %}
{% endtabs %}
## Common Issues
### Connection issues
The data flow fails with an authentication error
ChatGPT Ads API keys don't expire on their own, so an authentication failure almost always means the key itself is no longer valid:
* The key was deleted or rotated in the **Settings** tab of Ads Manager
* Your access to that ad account was removed
* The key was pasted with a leading or trailing space, or truncated on copy
Generate a fresh key in Ads Manager, then open the source settings in Coupler.io and reconnect with the new key. Paste it directly rather than retyping it.
I pasted a key but I'm seeing the wrong ad account's data
Each API key is scoped to exactly one ad account, and Coupler.io reads whichever account the key belongs to — there's no account picker to correct it afterwards. If the data belongs to a different account than you expected, you've used a key generated under that account.
Check the **Account: Account name** and **Account: Account Id** fields in the output to confirm which account you're actually pulling, then generate a key under the right account in Ads Manager and reconnect.
### Missing data
Only one of my ad accounts is in the report
This is expected. A key is scoped to one ad account, so one source returns one account.
To report across several accounts, add a separate ChatGPT Ads source for each one — same report type, same date range, its own key — inside the **same** data flow, then use the Append transformation in the dataset step to stack them into a single table. The `Account: Account name` and `Account: Account Id` fields keep the rows distinguishable after appending.
The Campaign conversions report is all zeros
The conversions report returns a row for every campaign in the account whether or not it recorded conversions, so rows of zeros are what "no conversions" looks like — not an error.
If every row is zero, check in order:
* **Is conversion tracking set up?** Conversions only appear once tracking is configured in your ad account. Without it, the report is structurally valid and numerically empty.
* **Is the date range one where conversions actually occurred?** Try widening it.
* **Are the campaigns in it ones that drive conversions?** Awareness campaigns legitimately report zero.
No rows at all for my date range
Two things to check:
* **Is the end date in the future?** A future end date makes the run fail rather than return rows. Keep the end date at today or earlier.
* **Confirm the account had delivery in that period.** A campaign that never served in the range produces no rows in the performance reports.
### Configuration issues
Monthly data starts earlier than my start date
Monthly buckets are aligned to calendar months. A start date of July 10 produces a bucket covering all of July, dated `2026-07-01` — so the first bucket reaches back before the date you picked.
If you need the range to begin exactly on your start date, use Daily granularity and roll up to months yourself in the dataset step.
### Data discrepancies
Numbers don't match what I see in Ads Manager
Work through these in order — the first two explain most mismatches:
* **Timezone.** The API reads your date range on the ad account's own clock, not UTC. Check the `Account: Timezone` field and make sure the Ads Manager view you're comparing uses the same window. A report pulled for "yesterday" in a US-Pacific account is a different 24 hours than UTC yesterday.
* **Grain.** Account-level totals won't match a campaign-level view, and the by-country report splits a campaign across many rows. Compare like with like.
* **Recent days still settling.** Coupler.io re-fetches the last 3 days on every run precisely because recent numbers can be restated. Reconcile against completed days rather than today or yesterday.
* **Summed ratio metrics.** If your CTR, CPC, or CPM looks wildly wrong, check whether your dashboard is summing or averaging them. They have to be recalculated from totals — see [Field reference](#field-reference).
Spend in the by-country report is several times too high
You're almost certainly summing the `Campaign: Total …` fields instead of the plain performance fields.
In the by-country report, each row carries both the country's own metrics *and* the campaign's total for that period. The campaign total is duplicated onto every country row, so a campaign that ran in 12 countries has its total spend repeated 12 times. Summing that column multiplies spend by the number of countries.
Sum `Cost: Amount spend` for country-level spend. Use `Campaign: Total spend` only as a per-row denominator — for example, to calculate each country's share of its campaign.
### Performance
A long date range at ad level is slow
Coupler.io splits long periods into chunks internally and saves progress as it goes, so a large backfill will complete — it just takes longer, and a run that times out resumes where it left off rather than starting over.
To make it faster, narrow what you're asking for: a shorter range, a coarser granularity, or a higher-level report type if you don't actually need per-ad rows. There's no need to break the pull into separate data flows by date — the splitting already happens for you.
## FAQ
How do I get a ChatGPT Ads API key?
Open [Ads Manager settings](https://ads.openai.com/settings) and generate an API key there. The key is shown only once, so copy it immediately. It grants full Ads Management API access — store it securely.
Note which ad account you generated it under: each key is scoped to one ad account, and that scope is what determines the data Coupler.io returns.
How is billing calculated for the ChatGPT Ads source?
Each ChatGPT Ads source connection counts as one account. A connection uses one API key, and a key is scoped to one ad account, so one connection always means one ad account.
If you report on several ad accounts, each one is its own connection and counts separately. Adding more report types for the same ad account doesn't add accounts.
For plan limits and pricing, see the [Coupler.io pricing page](https://www.coupler.io/pricing).
Do I need to reconnect periodically?
No. ChatGPT Ads API keys don't expire on a schedule, so a working connection keeps working.
You'll need to reconnect if the key is deleted or rotated in Ads Manager, or if your access to the ad account is removed. In that case, generate a new key and update it in the source settings.
{% hint style="info" %}
See [Connection issues](#connection-issues) for authentication troubleshooting.
{% endhint %}
Can I get more than one report type in a single table?
Not from one source — a source returns one report type. But you can load them side by side from one data flow.
Add each report type as a separate source in the same data flow and load each to its own table or sheet in the destination. Combine them there, matching campaign spend to campaign conversions on campaign ID and date. Joining or appending different report types in the dataset step is not recommended. There is no need for separate data flows.
What's the difference between click-through and view-through conversions?
Click-through conversions are attributed to people who clicked your ad before converting. View-through conversions are attributed to people who saw it without clicking.
The `Conversions: Conversions` field is the total of both. Keep all three columns in your report — if a cost-per-conversion figure looks surprisingly strong, the view-through share is usually where the explanation is.
How far back can I pull historical data?
Set whatever start date you need with the date picker and Coupler.io will work through the range, splitting it into chunks internally and checkpointing progress as it goes. A long backfill takes longer but completes, and resumes rather than restarting if a run times out.
Do the wide backfill once and leave the start date in place. On Daily or Monthly granularity, later scheduled runs only fetch new days.
Can I average the CTR or CPC columns in my dashboard?
No. They're ratios, so they can't be summed and shouldn't be averaged — averaging gives a day with 2 clicks the same weight as a day with 2,000.
Recalculate them at whatever level you're reporting: `CTR = SUM(clicks) / SUM(impressions)`, `CPC = SUM(spend) / SUM(clicks)`, `CPM = SUM(spend) / SUM(impressions) * 1000`.
What timezone is the data in?
Date buckets follow the ad account's timezone, which you'll find in the `Account: Timezone` field.
Can I combine ChatGPT Ads with Google Ads or Facebook Ads?
Yes. Add them as additional sources in the same data flow and use **Append** to stack them into one cross-channel table, mapping the shared columns — date, campaign name, impressions, clicks, spend — onto each other.
Recalculate ratio metrics after appending rather than carrying each platform's CTR or CPC through, since those won't combine meaningfully across sources.
Can I send ChatGPT Ads data to an AI tool?
Yes. Coupler.io supports AI destinations including ChatGPT, Claude, Gemini, Cursor, Perplexity, and OpenClaw, so you can route performance data straight into one for campaign summaries or optimization suggestions.
{% hint style="info" %}
**ChatGPT Ads and ChatGPT are different integrations.** ChatGPT Ads is the source this article covers; ChatGPT is a destination. Using ChatGPT Ads as the source and ChatGPT as the destination in one data flow is a perfectly normal setup.
{% 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/ppc/chatgpt-ads.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.