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

# Query synced Meta ads performance (spend, impressions, clicks, results, ROAS, budget) grouped by campaign / ad set / ad / creative component, over a date range. Use list_ad_accounts first to discover ad account ids. Data freshness depends on the team's sync schedule; check last_synced_at in list_ad_accounts.

> Query synced Meta ads performance (spend, impressions, clicks, results, ROAS, budget) grouped by campaign / ad set / ad / creative component, over a date range. Use list_ad_accounts first to discover ad account ids. Data freshness depends on the team's sync schedule; check last_synced_at in list_ad_accounts.



## OpenAPI

````yaml /openapi.json post /tools/query_performance
openapi: 3.1.0
info:
  title: AdStellar API
  version: 1.0.0
  description: >-
    Public REST API for AdStellar — creative generation, video generation,
    campaign management, and analytics. Every endpoint maps 1:1 to an AdStellar
    MCP tool.
servers:
  - url: https://app.adstellar.ai/api/v1
security: []
paths:
  /tools/query_performance:
    post:
      summary: >-
        Query synced Meta ads performance (spend, impressions, clicks, results,
        ROAS, budget) grouped by campaign / ad set / ad / creative component,
        over a date range. Use list_ad_accounts first to discover ad account
        ids. Data freshness depends on the team's sync schedule; check
        last_synced_at in list_ad_accounts.
      description: >-
        Query synced Meta ads performance (spend, impressions, clicks, results,
        ROAS, budget) grouped by campaign / ad set / ad / creative component,
        over a date range. Use list_ad_accounts first to discover ad account
        ids. Data freshness depends on the team's sync schedule; check
        last_synced_at in list_ad_accounts.
      operationId: query_performance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: https://json-schema.org/draft/2020-12/schema
              type: object
              properties:
                breakdown:
                  description: What to group by. Default "campaign".
                  type: string
                  enum:
                    - campaign
                    - ad_set
                    - ad
                    - ad_combination
                    - audience_variant
                    - creative
                    - headline
                    - primary_text
                    - description
                    - cta
                    - interest
                    - custom_audience
                    - lookalike
                    - behavior
                    - country
                    - landing_page
                    - audience
                    - placement
                preset:
                  description: Date-range preset. Default "last_7d".
                  type: string
                  enum:
                    - today
                    - yesterday
                    - last_7d
                    - last_14d
                    - last_30d
                    - last_90d
                    - mtd
                    - last_quarter
                    - lifetime
                startDate:
                  description: Explicit range start (YYYY-MM-DD), use with endDate.
                  type: string
                endDate:
                  description: Explicit range end (YYYY-MM-DD).
                  type: string
                adAccount:
                  description: Ad account name or id. Omit for the whole workspace.
                  type: string
                campaignId:
                  description: Drill into one campaign (its ad sets or ads).
                  type: string
                adSetId:
                  description: Drill into one ad set (its ads).
                  type: string
                limit:
                  description: Max rows (default 50).
                  type: integer
                  minimum: 1
                  maximum: 50
                workspaceId:
                  description: >-
                    Which workspace to query (must be one this credential can
                    access). Omit for the primary workspace.
                  type: string
                  format: uuid
                  pattern: >-
                    ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
              additionalProperties: false
      responses:
        '200':
          description: Tool result
        '401':
          description: Missing or invalid API key
        '403':
          description: Missing required scope
        '429':
          description: Rate limit exceeded
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: AdStellar API key (ast_live_...)

````