Run GAQL Query
Execute Google Ads Query Language (GAQL) query via Google Ads API for advanced data retrieval
The Run GAQL Query node lets you execute custom Google Ads Query Language (GAQL) queries directly against the Google Ads API. This advanced node provides access to all resources and fields that Google Ads API offers, giving you complete flexibility when the standard Get Report node doesn’t have the data you need.
When to Use It
Use this node when:
- Data isn’t available in Get Report: You need specific fields, resources, or data combinations not supported by the standard reporting node
- Advanced filtering requirements: You need complex WHERE clauses or JOIN operations beyond basic filters
- Custom data relationships: You want to fetch data from multiple Google Ads resources in a single query
- Specific API resources: You need access to account structure, extensions, keywords, ads, or other non-reporting resources
- Expert-level control: You’re comfortable with GAQL syntax and want full control over your data queries
What is GAQL?
Google Ads Query Language (GAQL) is a SQL-like query language that lets you retrieve data from the Google Ads API. It provides:
- Direct API access: Query any resource available in the Google Ads API
- Flexible data selection: Choose exactly which fields you want to retrieve
- Advanced filtering: Use complex WHERE conditions with multiple operators
- Resource relationships: Access related data across different Google Ads entities
- Performance optimization: Write efficient queries for large datasets
Inputs
| Field | Type | Required | Description |
|---|---|---|---|
| Account | Single-select | Yes | Select one Google Ads account to query |
| GAQL Query | Text area | Yes | Enter the GAQL query to execute |
Query Builder Tool (Recommended)
The easiest way to create GAQL queries is using Google’s visual Query Builder tool:
Access Google Ads Query Builder
The Query Builder lets you:
- Generate queries visually: Select resources and fields through a user interface - no coding required
- Validate syntax: Ensures your queries are properly formatted
- Discover available fields: Browse all available resources and their fields
- Test queries: Verify your queries before using them in workflows
- Learn GAQL: See how your selections translate to GAQL syntax
How to use it:
- Visit the Query Builder link above
- Select your resource (e.g., “campaign”, “ad_group”, “keyword_view”)
- Choose the fields you want to retrieve
- Add any filters or conditions
- Copy the generated query and paste it into this node
Example Queries:
1. Get all campaigns with their status
2. Get keywords with quality scores
Output
The node returns raw data from the Google Ads API based on your GAQL query. The output structure depends entirely on the fields you select in your query.
Sample Output:
| campaign_id | campaign_name | campaign_status | impressions | clicks |
|---|---|---|---|---|
| 123456789 | Holiday Campaign 2024 | ENABLED | 15,432 | 876 |
| 987654321 | Summer Sale 2024 | ENABLED | 8,901 | 234 |
| 456789123 | Brand Awareness | PAUSED | 12,345 | 345 |
Can be passed to:
- AI Analyze Data for insights and analysis
- Google Sheets for detailed data export
- Data transformation nodes for further processing
- Email or Slack for reporting
Credit Cost
- Cost per run: 1 credit (per successful execution)
Example Setup
FAQs
How is this different from the Get Report node?
How is this different from the Get Report node?
The Get Report node provides a user-friendly interface for common reporting needs with pre-defined metrics and dimensions. Run GAQL Query gives you:
- Complete API access: Query any Google Ads resource, not just reporting data
- Custom field selection: Choose exactly which fields you need
- Advanced relationships: Access data relationships not available in standard reports
- Expert control: Full GAQL syntax for complex queries
- Raw API data: Direct access to Google’s data without pre-processing
Use Get Report for standard performance reporting, and GAQL for specialized data needs.
Do I need to know SQL to use this node?
Do I need to know SQL to use this node?
No! You don’t need to know SQL or any programming language.
Use the Query Builder instead:
- Click the Query Builder link in the node or visit it directly
- Select your data visually - choose resources, fields, and filters through dropdowns and checkboxes
- Copy the generated query - the tool creates the GAQL syntax for you
- Paste into this node - no coding required!
The Query Builder makes GAQL accessible to everyone, regardless of technical background. You can build complex queries by simply clicking and selecting what data you want.
For advanced users: If you’re comfortable with SQL-like syntax, you can write queries manually, but it’s not necessary.
Why is my query returning an error?
Why is my query returning an error?
Common GAQL query errors:
- Invalid field names: Use exact field names from Google’s documentation
- Resource compatibility: Not all fields are available for every resource
- Date format: Use ‘YYYY-MM-DD’ format for dates
- Syntax errors: Check for missing commas, quotes, or keywords
- Field limits: Some resources have restrictions on field combinations
Use the Query Builder to validate your syntax before running queries.
Can I query data from multiple accounts?
Can I query data from multiple accounts?
No, each query runs against a single Google Ads account. For multi-account reporting:
- Run separate queries: Use multiple GAQL nodes for different accounts
- Use Get Report node: The standard reporting node supports multi-account queries
- Combine downstream: Merge results using data processing nodes
This limitation ensures query performance and data consistency.
What's the maximum amount of data I can retrieve?
What's the maximum amount of data I can retrieve?
The Google Ads API has a maximum limit of 10,000 rows per query. Other considerations include:
- Row limit: Maximum 10,000 rows per query - use LIMIT clause or pagination for large datasets
- Field limit: Maximum number of fields depends on the resource
- Date range: Large date ranges may timeout or return partial data
- API quotas: Google Ads API has rate limits and quotas
For datasets larger than 10,000 rows, break queries into smaller time periods or use more specific filters to reduce data volume.
How do I find available fields for each resource?
How do I find available fields for each resource?
Use the Query Builder - it’s the easiest way:
The Query Builder shows you:
- All available resources (campaigns, ad groups, keywords, etc.)
- All fields for each resource with descriptions
- Compatible field combinations - it only shows valid options
- Real-time validation - ensures your selections work together
Other resources:
- API Documentation: Complete field reference for advanced users
- Examples in this documentation: Sample queries for common use cases
Pro tip: Start with the Query Builder to explore what’s available, then bookmark the combinations you use frequently.
How do I optimize query performance?
How do I optimize query performance?
To improve GAQL query performance:
- Use specific date ranges: Avoid querying unnecessary date periods
- Limit rows: Add LIMIT clause to control result size
- Filter early: Use WHERE clauses to reduce data before processing
- Select only needed fields: Don’t retrieve fields you won’t use
- Avoid complex joins: Keep queries simple when possible
Well-optimized queries run faster and use fewer API resources.