> ## Documentation Index
> Fetch the complete documentation index at: https://docs.markifact.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run GAQL Query

> Executes custom Google Ads Query Language (GAQL) queries to retrieve any resource information from Google Ads API like campaign settings, budgets, bids, audiences, extensions, assets, keywords, ads...

Executes custom Google Ads Query Language (GAQL) queries to retrieve any resource information from Google Ads API like campaign settings, budgets, bids, audiences, extensions, assets, keywords, ads, ad groups, search terms, conversion actions, bidding strategies, labels, locations, and shared sets. Prefer using the standard `gads_get_report` operation for normal performance reporting; use `gads_run_gaql_query` for advanced or unsupported reporting queries, resource lookups, or fields not covered by `gads_get_report`. If the exact FROM resource, metric, segment, or field compatibility is unclear, use `gads_search_gaql_resources` as an optional discovery helper. Note: Column names in the output replace dots with underscores for easier access. For example, campaign.id becomes campaign\_id. IMPORTANT: monetary fields are returned as raw values from Google in micros (1/1,000,000 of currency unit, e.g. 50000000 = \$50). This includes any field whose name contains 'micros' (cost\_micros, campaign\_budget\_amount\_micros, average\_cpc, average\_cpm, etc.) — divide by 1,000,000 to get the actual dollar amount before passing to write operations like gads\_update\_campaign\_budget.

|                      |                       |
| -------------------- | --------------------- |
| **App**              | Google Ads            |
| **Operation ID**     | `gads_run_gaql_query` |
| **Type**             | Action                |
| **Connection**       | `gads` (required)     |
| **Credits per run**  | 1                     |
| **Agent / MCP tool** | Yes                   |
| **Versions**         | 1, 2 (default: 2)     |

## Inputs

| Field                 | Type                                                              | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                            |
| --------------------- | ----------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account`             | GadsAccountItem or object or array of object or string or integer | Yes      | -       | Select the Google Ads account, ask the user for it if not provided                                                                                                                                                                                                                                                                                                                                                                     |
| `account_id`          | string                                                            | No       | -       |                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `customer_id`         | string                                                            | No       | -       |                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `customer`            | string                                                            | No       | -       |                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `customerId`          | string                                                            | No       | -       |                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `manager_id`          | string                                                            | No       | -       |                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `login_customer_id`   | string                                                            | No       | -       |                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `manager_customer_id` | string                                                            | No       | -       |                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `loginCustomerId`     | string                                                            | No       | -       |                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `query`               | string                                                            | Yes      | -       | Enter the Google Ads Query Language (GAQL) query to run for the selected account. Use this when the standard `gads_get_report` operation does not cover the needed Google Ads data. If the correct FROM resource, metric, segment, or field compatibility is unclear, use `gads_search_gaql_resources` operation as an optional discovery helper before building the query. Queries should use fields supported by Google Ads API v25. |
| `validate_only`       | boolean                                                           | No       | `False` | When true, validates the GAQL query using Google Ads Search without executing it or returning rows.                                                                                                                                                                                                                                                                                                                                    |

### GadsAccountItem

| Field       | Type   | Required | Default | Description                                                                                                                                                    |
| ----------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`     | string | Yes      | -       |                                                                                                                                                                |
| `label`     | string | Yes      | -       |                                                                                                                                                                |
| `managerId` | string | Yes      | -       | The manager ID for the Google Ads account. Ask  user to use the dropdown to select accounts, this manager id is selected background and not shown to the user. |

## Output

**Type**: `List[Dict]`

Returns query results as rows, each row is a dict with keys matching selected fields. Note: Column names in the output replace dots with underscores for easier access. For example, campaign.id becomes campaign\_id.

**Fields**: dynamic (depend on the inputs)