> 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/snapchat-ads.md).

# Snapchat Ads

Connect Snapchat Ads to Coupler.io to auto-export campaign performance, ad group metrics, and audience data to Google Sheets, BigQuery, or Excel.

Snapchat Ads lets you run targeted advertising campaigns across Snapchat, Snap Audience Network, and other placements. With Coupler.io, you can automatically export your campaign performance, ad group metrics, individual ad data, and audience insights to your favorite analytics tools—no coding required.

## Why connect Snapchat Ads to Coupler.io?

* **Centralize your ad metrics** — Pull campaign, ad group, and ad-level performance data into Google Sheets, Excel, BigQuery, or Looker Studio
* **Track audience insights** — Export demographic and geographic breakdowns to understand who's engaging with your ads
* **Automate reporting** — Set up scheduled data flows to refresh your dashboards and reports on your preferred cadence
* **Combine with other data** — Join Snapchat data with Facebook Ads, Google Ads, or other sources to compare performance across channels
* **Feed AI tools** — Send performance summaries to Claude, ChatGPT, or Perplexity for automated insights and analysis

## Prerequisites

* A Snapchat Ads Manager account with at least one active ad account
* Access to create or manage ad accounts (you'll authorize Coupler.io via OAuth)
* A destination to export data to (Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination)

## Quick start

{% hint style="success" %}
Snapchat Ads uses OAuth, so you'll sign in with your Snapchat Ads Manager credentials. No API key needed. After connecting, you can preview your data before running the flow.
{% endhint %}

## How to connect

{% stepper %}
{% step %}
**Create a new data flow.** In Coupler.io, click "Create a new data flow" and select Snapchat Ads as your source.
{% endstep %}

{% step %}
**Sign in to Snapchat Ads Manager.** Click the OAuth sign-in button and authorize Coupler.io to access your Snapchat Ads data. You'll be prompted to log in with your Snapchat Ads Manager credentials.
{% endstep %}

{% step %}
**Select your ad accounts.** Choose which ad accounts you want to pull data from. You can select multiple accounts if you manage more than one.
{% endstep %}

{% step %}
**Choose a report type.** Select what data you want to export—for example, "Campaign performance," "Ad group performance," or "List of Ads." Performance reports include metrics like impressions, clicks, spend, and conversions. List reports show your campaigns, ad groups, ads, creatives, or media without performance metrics.
{% endstep %}

{% step %}
**Set the date range (for performance reports).** If you've selected a performance report, use the date picker to set your start and end dates. The date range is required for performance data.
{% endstep %}

{% step %}
**Choose how to split your data.** For performance reports, decide whether you want metrics broken down by day, month, or as totals. Select "Daily" for day-by-day performance, "Monthly" for rolling monthly totals, or "Totals" for the entire date range combined.
{% endstep %}

{% step %}
**Pick your destination.** Select where you want the data to go—Google Sheets, Excel, BigQuery, Looker Studio, or an AI tool like Claude or ChatGPT.
{% endstep %}

{% step %}
**Run your data flow.** Click "Run" to execute a test pull of your data. Once it completes successfully, you can review the data in your destination and set up a schedule if needed.
{% endstep %}
{% endstepper %}

## Report types overview

| Report Type                       | What It Shows                                                 | Best For                                 |
| --------------------------------- | ------------------------------------------------------------- | ---------------------------------------- |
| Campaign performance              | Metrics by campaign (impressions, clicks, spend, conversions) | Tracking overall campaign ROI            |
| Ad group performance              | Metrics by ad group (called "Ad Squad" in Snapchat)           | Optimizing audience targeting            |
| Ad performance                    | Metrics by individual ad                                      | Comparing creative performance           |
| Campaign geo\&demography insights | Campaign metrics broken down by age, gender, location, device | Understanding who engages with campaigns |
| Ad group geo\&demography insights | Ad group metrics by demographic and location                  | Targeting adjustments                    |
| Ad geo\&demography insights       | Ad metrics by demographic and location                        | Creative refinement                      |
| List of Campaigns                 | Names, IDs, status of all campaigns                           | Inventory management                     |
| List of Ad groups                 | Names, IDs, status of all ad groups                           | Structure reference                      |
| List of Ads                       | Names, IDs, status, type of all ads                           | Ad library audit                         |
| List of Creatives                 | Creative assets and metadata                                  | Asset management                         |
| List of Media                     | Media files and metadata                                      | Media library reference                  |

## Snapchat Ads data overview

Snapchat Ads provides two categories of reports: **performance metrics** (with impressions, clicks, spend, conversions) and **entity lists** (showing your campaigns, ads, and creative assets).

## Report types

| Report Type                       | Contains                                                                              | Date Range Required? | Customizable Metrics? |
| --------------------------------- | ------------------------------------------------------------------------------------- | -------------------- | --------------------- |
| Campaign performance              | Campaign-level metrics with optional demographic/geographic breakdown                 | Yes                  | Yes                   |
| Ad group performance              | Ad group–level metrics with optional demographic/geographic breakdown                 | Yes                  | Yes                   |
| Ad performance                    | Ad-level metrics with optional demographic/geographic breakdown                       | Yes                  | Yes                   |
| Campaign geo\&demography insights | Campaign metrics split by age, gender, country, region, device, or lifestyle category | Yes                  | Yes                   |
| Ad group geo\&demography insights | Ad group metrics split by demographics and location                                   | Yes                  | Yes                   |
| Ad geo\&demography insights       | Ad metrics split by demographics and location                                         | Yes                  | Yes                   |
| List of Campaigns                 | Campaign names, IDs, status, creation date, objective                                 | No                   | No                    |
| List of Ad groups                 | Ad group names, IDs, status, targeting info                                           | No                   | No                    |
| List of Ads                       | Ad names, IDs, status, type, placement                                                | No                   | No                    |
| List of Creatives                 | Creative asset IDs, type, format, dimensions                                          | No                   | No                    |
| List of Media                     | Media file IDs, type, size, format                                                    | No                   | No                    |

## Available metrics

#### Spend and impressions

| Metric                         | Definition                                            |
| ------------------------------ | ----------------------------------------------------- |
| Spend                          | Total amount spent (in account currency)              |
| Impressions                    | Total number of ad impressions                        |
| Swipe-throughs                 | Number of users who swiped the ad                     |
| Impressions (frequency capped) | Impressions after deduplication within frequency caps |

#### Engagement

| Metric                   | Definition                                                       |
| ------------------------ | ---------------------------------------------------------------- |
| Clicks                   | Total clicks on the ad                                           |
| Click-through rate (CTR) | Clicks ÷ impressions                                             |
| Average frequency        | Average number of times an impression was shown to a unique user |
| Shares                   | Number of users who shared the ad                                |
| Video views              | Number of video views (for video ads)                            |
| Quartile 1–4 views       | Video completion percentage (25%, 50%, 75%, 100%)                |

#### Conversions

| Metric                    | Definition                                                  |
| ------------------------- | ----------------------------------------------------------- |
| Conversions               | Total conversions attributed within the selected window     |
| Conversion rate           | Conversions ÷ clicks                                        |
| Conversion value          | Total value of conversions (requires Conversions API setup) |
| Purchase conversion value | Revenue from purchase conversions                           |
| App installs              | Mobile app installations attributed to the ad               |
| Mobile app installs       | App installs attributed to mobile users                     |
| Uninstalls                | App uninstalls attributed to the ad                         |

#### Cost and efficiency

| Metric                    | Definition                          |
| ------------------------- | ----------------------------------- |
| Cost per click (CPC)      | Spend ÷ clicks                      |
| Cost per conversion (CPA) | Spend ÷ conversions                 |
| Cost per swipe            | Spend ÷ swipes                      |
| Return on ad spend (ROAS) | Conversion value ÷ spend            |
| Acquisition cost          | Similar to CPA; varies by objective |

## Available dimensions for geo\&demography reports

#### Audience dimensions

| Dimension                   | Available Values                                               | Notes                                    |
| --------------------------- | -------------------------------------------------------------- | ---------------------------------------- |
| Age                         | 13–17, 18–24, 25–34, 35–44, 45–54, 55–64, 65+                  | Snapchat's age estimation                |
| Gender                      | Male, Female, Unknown                                          | Based on user profile                    |
| Age + Gender                | All combinations of above                                      | Provides granular segmentation           |
| Country                     | ISO country codes (e.g., US, GB, CA)                           | Based on IP and profile                  |
| Country + Device OS         | Country paired with iOS, Android                               | Shows platform mix by geography          |
| Device Make                 | Apple, Samsung, OnePlus, etc.                                  | Hardware manufacturer                    |
| Device OS                   | iOS, Android                                                   | Operating system                         |
| DMA                         | US metro areas (e.g., New York, Los Angeles)                   | Available for US-targeted campaigns only |
| Region                      | US states                                                      | Available for US-targeted campaigns only |
| Snapchat Lifestyle Category | Entertainment, Fashion, Food & Drink, Sports, Technology, etc. | User interest categories                 |

## Attribution windows

Conversion metrics use **attribution windows** to determine which conversions are credited to your ads. Snapchat supports:

* **Post-view windows**: 1 hour, 3 hours, 6 hours, 1 day, 7 days, or 28 days after an impression
* **Post-swipe windows**: 1 day, 7 days, or 28 days after a user swipes (clicks) the ad

You can combine any post-view window with any post-swipe window. If you don't specify an attribution window, Snapchat applies defaults: 1 day post-view and 28 days post-swipe.

## Common metric combinations

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Campaign ROI analysis</strong></td><td>Spend, Conversions, Conversion Value, ROAS. Use "Campaign performance" report split by "Monthly" to track trends over time.</td></tr><tr><td><strong>Demographic targeting performance</strong></td><td>Conversions, Spend, Age, Gender from a geo&#x26;demography insights report. Compare CPA by age group to refine targeting.</td></tr><tr><td><strong>Geographic expansion</strong></td><td>Impressions, Clicks, Conversions, Country from geo&#x26;demography report. Identify underperforming regions for optimization.</td></tr><tr><td><strong>Creative testing</strong></td><td>Ad performance report with CTR, Video Views (Q1–Q4), Conversions. Compare metrics across ad creative variants.</td></tr><tr><td><strong>Platform performance</strong></td><td>Use "Country + Device OS" dimension to compare iOS vs. Android performance and spending allocation.</td></tr></tbody></table>

## Conversion breakdown

When pulling performance reports, you can optionally break conversions down by source:

| Breakdown Type     | Definition                                               |
| ------------------ | -------------------------------------------------------- |
| Total              | All conversions (default)                                |
| Web                | Conversions from web visits                              |
| App                | Conversions from mobile app interactions                 |
| Offline            | Conversions tracked via Store Visits API or offline data |
| Total off-platform | Conversions outside Snapchat ecosystem                   |
| Total on-platform  | Conversions within Snapchat (e.g., Snap Shop purchases)  |

## Use cases by role

{% tabs %}
{% tab title="Performance Marketers" %}
**Weekly performance dashboards** — Export campaign and ad group performance reports split by "Daily" with metrics like spend, conversions, ROAS, and CPA. Use date pickers to pull last 7 or 30 days and refresh data daily or weekly.

**Creative testing** — Pull ad-level performance reports to compare metrics (CTR, video completion %, conversion rate) across different creative assets. Use Coupler's Join transformation to combine with your ad management system for unified creative performance analysis.

**Demographic targeting** — Export geo\&demography insights (age, gender, country) to identify which audience segments convert best and at what cost. Use this to refine Snapchat targeting and budget allocation.
{% endtab %}

{% tab title="Finance & Operations" %}
**Spend tracking** — Pull campaign performance data split by "Monthly" to match Snapchat spend against invoices and financial records. Schedule a monthly refresh on the last day of each month.

**Budget vs. actual** — Combine Snapchat performance data with your budget spreadsheet using Coupler's Join transformation to compare planned vs. actual spend and ROI by campaign or account.

**Multi-channel reporting** — Append Snapchat data to Facebook Ads and Google Ads exports to create a unified advertising spend report across platforms.
{% endtab %}

{% tab title="Analytics & BI Teams" %}
**Snapchat data in BI tools** — Feed campaign and ad group performance reports into BigQuery, Looker Studio, or your preferred BI platform for dashboard and model building.

**Cross-platform attribution** — Join Snapchat metrics (conversions, spend) with web analytics data to measure Snapchat's contribution to overall marketing goals.

**Entity audits** — Export "List of Campaigns," "List of Ad groups," and "List of Ads" to maintain an inventory of active ads and identify orphaned or paused assets.
{% endtab %}
{% endtabs %}

## Platform-specific notes

* **Conversion data delays**: Snapchat's conversion tracking has a 24–48 hour reporting lag. Schedule data flows accordingly for near-real-time dashboards.
* **Attribution windows matter**: The same conversion might be counted differently depending on your attribution window selection. Choose a window that matches your business model (e.g., 28 days post-swipe for longer consideration cycles).
* **Demographic accuracy**: Age and gender data is based on Snapchat user profiles and may not be 100% complete. Expect 5–10% "Unknown" values.
* **DMA and Region dimensions**: Available only for campaigns targeted to the US. If you target other countries, these dimensions will not appear.
* **Placement performance**: Snapchat automatically optimizes placement across Snapchat, Audience Network, and other venues. Use dimension filters or advanced filters to isolate performance by placement type if needed.
* **Video metrics**: Quartile views and video completion metrics are only available for video ads. Carousel and static ads will show null or zero values.
* **API rate limits**: High-frequency refreshes on large multi-account data flows may hit Snapchat's API limits. If you see throttling errors, extend the interval between scheduled runs.

## Snapchat Ads common issues

### Connection issues

<details>

<summary>I signed in with OAuth but my ad accounts don't appear in the dropdown</summary>

This usually means your Snapchat account doesn't have permission to manage ads. Verify:

1. You're logged into Snapchat Ads Manager (not just Snapchat social)
2. Your account is assigned an admin or analyst role at the organization or account level
3. At least one ad account is active and not archived

If you manage multiple organizations, you may need to re-authorize and select the correct organization during the OAuth flow.

</details>

<details>

<summary>Authorization keeps failing or timing out</summary>

Try these steps:

1. Clear your browser cookies for both Coupler.io and Snapchat
2. Log out of Snapchat Ads Manager and log back in
3. Start the OAuth flow again from Coupler.io
4. If you use single sign-on (SSO) or two-factor authentication, make sure it's enabled on your Snapchat account before authorizing

If it still fails, wait a few minutes and try again—Snapchat's OAuth endpoints occasionally experience brief delays.

</details>

### Missing data

<details>

<summary>My data flow runs but returns empty or very few rows</summary>

Common causes:

1. **Date range issue**: Check that your start date is before your end date and that campaigns actually ran during that period
2. **Wrong report type**: "List" reports (List of Campaigns, List of Ads) don't include metrics. If you need metrics, choose a performance report instead
3. **No historical data**: If a campaign just launched, it may not have data yet. Snapchat typically shows data 24–48 hours after ads go live
4. **Advanced filters**: If you've applied filters, verify they match your campaign structure (e.g., if you filter by campaign name, make sure the name matches exactly)

Run a manual test with a broader date range (e.g., last 90 days) to check if data exists at all.

</details>

<details>

<summary>Campaign or ad names aren't showing in my data</summary>

Snapchat's API sometimes returns campaign or ad IDs without friendly names, especially if names contain special characters or if the ad/campaign was recently created or renamed.

**Solution**: Export a "List of Campaigns" or "List of Ads" report and use Coupler's **Join** transformation to combine it with your performance report. This ensures you always have names paired with metrics.

Example: Join performance data on `campaign_id` = `id` to add `campaign_name` to your performance rows.

</details>

<details>

<summary>Demographic or geographic breakdowns are missing or show mostly null values</summary>

This can happen for a few reasons:

1. **Wrong dimension for your targeting**: If your campaign targets multiple countries, selecting "DMA" or "Region" (US-only dimensions) will return no data. Use "Country" instead
2. **Insufficient data**: If a segment has very few impressions or conversions, Snapchat may suppress the data for privacy. Try a wider date range
3. **Dimension not supported**: Make sure the dimension you selected matches the report type. For example, you can't use demographic dimensions with "List of Campaigns"

Check that your chosen dimension aligns with your campaign's targeting and geo footprint.

</details>

<details>

<summary>Conversion data is showing zero or much lower than expected</summary>

Snapchat conversion reporting depends on proper setup:

1. **Conversions API not configured**: If you haven't installed Snapchat's Conversions API on your website or mobile app, conversion tracking will be incomplete
2. **Attribution window mismatch**: Conversions are only credited within your selected attribution window. If someone converts 30 days after seeing an ad, and you've chosen "1 day post-view," that conversion won't be counted
3. **24–48 hour reporting lag**: Snapchat doesn't report conversions in real time. Wait a full business day before assuming data is complete
4. **Pixel not firing**: Double-check that your Snapchat pixel is installed correctly and firing on conversion events

Verify conversion attribution window settings in your data flow and compare with Snapchat Ads Manager to ensure they match.

</details>

### Permission errors

<details>

<summary>"Access denied" or "Unauthorized" error during the OAuth flow</summary>

You likely don't have the required permissions. Check:

1. Your Snapchat user role is **Admin** or **Analyst** (not Viewer-only)
2. Your role is assigned at the organization level, not just a single ad account (organization permissions are required)
3. Your account isn't restricted by IP allowlisting or other security policies

If you're part of an agency, your client may need to add you as an admin or grant you specific ad account access. Contact your organization's Snapchat administrator.

</details>

<details>

<summary>I can authorize but only see one ad account when I manage multiple</summary>

This happens if:

1. Your user role has access to only that one account (check with your org admin)
2. Some accounts are archived—Coupler.io only shows active accounts
3. You authorized via a sub-account instead of the main organization account

You can re-authorize by disconnecting and signing in again, making sure you're using the main organization account that has visibility across all ad accounts.

</details>

### Data discrepancies

<details>

<summary>Numbers in Coupler.io don't match Snapchat Ads Manager</summary>

Small discrepancies (1–5%) are normal due to rounding and real-time data updates. Larger gaps usually indicate:

1. **Different date ranges**: Verify your start and end dates match exactly (including time zone)
2. **Different split settings**: If Coupler is set to "Daily" and Ads Manager shows "Totals," numbers won't align. Use "Totals" in Coupler for a 1:1 comparison
3. **Different attribution windows**: Conversion counts will differ if you've selected a different attribution window in Coupler than in Ads Manager
4. **Dimension filtering**: If you've selected a demographic or geographic dimension, you're seeing a subset of data, not totals

Run the same report in both Snapchat Ads Manager and Coupler using identical settings to verify alignment.

</details>

<details>

<summary>My data flow exported duplicate rows</summary>

Duplicates can occur if:

1. **You ran the flow multiple times**: Each run appends data. Check your destination's existing data
2. **The report type includes a grouping dimension**: Reports with demographic or geographic breakdowns naturally produce multiple rows per campaign (one per age group, gender, etc.)
3. **You appended data from multiple sources**: If you're combining Snapchat data with other data sources using Append, verify you're not doubling up on any rows

If true duplicates appear (identical rows), check your advanced filter settings—you may have accidentally included overlapping filters.

</details>

<details>

<summary>Performance metrics look too high or too low compared to similar campaigns</summary>

1. **Check your filter settings**: Advanced filters may be including or excluding certain data
2. **Verify conversion breakdown**: If you've selected "Web" conversions only, you won't see app or offline conversions
3. **Review the date range and split**: Ensure the period and granularity (daily vs. monthly vs. totals) match what you're comparing to
4. **Confirm the metric definition**: Some platforms use different calculation methods for metrics like CTR or ROAS

Export the same report from Snapchat Ads Manager alongside your Coupler.io export and compare settings side by side.

</details>

### Rate limits

<details>

<summary>Data flow fails with "API rate limit exceeded" or "quota exceeded" error</summary>

Snapchat's API has rate limits that vary by endpoint. If you hit a limit:

1. **Reduce the scope**: Pull data for fewer ad accounts, shorter date ranges, or fewer metrics
2. **Increase the refresh interval**: Instead of running hourly, schedule the flow to run once daily or once every 6 hours
3. **Split into multiple flows**: Create separate data flows for different report types or ad accounts to distribute API calls

For large-scale multi-account setups, consider running performance reports during off-hours (e.g., midnight to 6 AM) to avoid peak usage times.

</details>

<details>

<summary>Scheduled runs are failing intermittently but manual runs work</summary>

This can indicate throttling during peak hours or insufficient API quota for frequent refreshes. Try:

1. **Space out scheduled runs**: Change from hourly to every 2–4 hours, or to once daily
2. **Schedule off-peak refreshes**: Set your data flow to run outside of 9 AM–5 PM (US business hours)
3. **Reduce the date range**: Instead of pulling 90 days every run, pull only the last 7 days and append to historical data

If you absolutely need real-time data, contact Snapchat support to request a higher API quota for your organization.

</details>

## Snapchat Ads FAQ

<details>

<summary>What's the difference between "Campaign performance" and "Campaign geo&#x26;demography insights"?</summary>

"Campaign performance" gives you your core metrics (spend, impressions, clicks, conversions, ROAS, etc.) rolled up by campaign, no segmentation. "Campaign geo\&demography insights" gives you the same metrics, but broken down by a dimension you choose—like age, gender, country, or device OS. So if you have one campaign spending $1,000, campaign performance shows one row. Campaign geo\&demography with "Age" selected shows multiple rows (one per age group) totaling $1,000. Use "Campaign performance" for top-level ROI tracking, and geo\&demography when you want to understand which audience segments are performing best.

</details>

<details>

<summary>Can I combine data from multiple ad accounts in one data flow?</summary>

Yes. In the "Ad accounts" step, select all the accounts you want to include. The exported data will have an "account\_id" or "account\_name" column so you can distinguish which rows came from which account. You can then use Coupler's **Append** transformation to combine them in your destination, or keep them as separate tabs/tables and join them in your analytics tool.

</details>

<details>

<summary>Why are my ad or campaign names missing from the performance data?</summary>

Snapchat's API sometimes returns IDs without the corresponding names, especially for newly created or renamed ads. **Solution**: Export a "List of Ads" or "List of Campaigns" report (no date range required) and use Coupler's **Join** transformation to add names to your performance data. Join on the campaign\_id or ad\_id field.

For example:

* Flow 1: Campaign performance report → Google Sheets tab "Performance"
* Flow 2: List of Campaigns → Google Sheets tab "Campaigns"
* Use Join in Coupler to match performance data to campaign names on campaign\_id

</details>

<details>

<summary>What attribution window should I use?</summary>

It depends on your sales cycle. Recommended starting points:

* **E-commerce with fast checkout**: 1 day post-swipe (user converts immediately)
* **B2B or longer consideration**: 7–28 days post-swipe (includes days for research/decision)
* **Brand awareness or view-through conversions**: Use a post-view window (1 hour, 3 hours, or 1 day) alongside post-swipe

If unsure, start with the default (1 day post-view + 28 days post-swipe). You can always change the attribution window and re-run historical data to compare.

</details>

<details>

<summary>Can I use advanced filters to narrow down my data?</summary>

Yes, if the report type supports it (all performance reports and list reports do). You can filter by campaign name, status, objective, or custom properties. The syntax varies—usually you'll see a dropdown to select the field and a text box for the value. Filters reduce the data returned, which can help if you only need a subset of campaigns (e.g., "Active campaigns only").

If you're not sure whether your filter worked, run a manual test and check the output rows to verify.

</details>

<details>

<summary>Why does my data show zero conversions when Snapchat Ads Manager shows conversions?</summary>

Check these three things:

1. **Attribution window**: The conversion might fall outside your selected window. For example, if someone converts 2 days after swiping and you've selected "1 day post-swipe," that conversion won't be counted. Try "28 days post-swipe" to match Snapchat Ads Manager's default.
2. **Conversion type**: If you've selected "Web" conversions only and the conversion came from an app, it won't show. Try the "Total" breakdown to see all conversions.
3. **Reporting lag**: Snapchat has a 24

</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/ppc/snapchat-ads.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.
