AdListResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/adspendspy/main/json-schema/adspendspy-ad-list-response-schema.json",
  "title": "AdListResponse",
  "x-generated": "2026-10-27",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/adspendspy-api-openapi.json#/components/schemas/AdListResponse",
  "type": "object",
  "required": [
    "success",
    "ads",
    "pagination",
    "summary",
    "meta"
  ],
  "properties": {
    "success": {
      "type": "boolean",
      "enum": [
        true
      ]
    },
    "ads": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/AdSummary"
      }
    },
    "pagination": {
      "type": "object",
      "required": [
        "next_cursor",
        "has_more",
        "total"
      ],
      "properties": {
        "next_cursor": {
          "type": [
            "string",
            "null"
          ],
          "description": "Send as cursor with the same filters for the next page; null on the last page."
        },
        "has_more": {
          "type": "boolean"
        },
        "total": {
          "type": "integer",
          "description": "All ads that match the filters."
        }
      }
    },
    "summary": {
      "type": "object",
      "required": [
        "estimated_spend",
        "currency",
        "spend_basis"
      ],
      "properties": {
        "estimated_spend": {
          "type": "number",
          "description": "Summed estimate in EUR over all matching ads."
        },
        "currency": {
          "type": "string",
          "enum": [
            "EUR"
          ]
        },
        "spend_basis": {
          "type": "string",
          "enum": [
            "latest_cumulative_estimate"
          ]
        }
      }
    },
    "meta": {
      "$ref": "#/$defs/SpendMeta"
    }
  },
  "$defs": {
    "AdSummary": {
      "type": "object",
      "required": [
        "id",
        "internal_ad_id",
        "page_id",
        "ad_id",
        "meta_ad_id",
        "media_type",
        "estimated_spend",
        "spend_coverage"
      ],
      "properties": {
        "id": {
          "type": "integer",
          "description": "Internal ad ID; same value as internal_ad_id."
        },
        "internal_ad_id": {
          "type": "integer",
          "description": "Pass this value to ads/details.php as ad_id."
        },
        "page_id": {
          "type": "string",
          "pattern": "^[0-9]{5,25}$",
          "description": "Meta advertiser page ID, kept as a string."
        },
        "ad_id": {
          "type": "string",
          "description": "Meta ad ID; same value as meta_ad_id."
        },
        "meta_ad_id": {
          "type": "string",
          "description": "Identifies the ad on Meta. Never accepted as ad_id."
        },
        "ad_archive_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "headline": {
          "type": [
            "string",
            "null"
          ]
        },
        "body_text": {
          "type": [
            "string",
            "null"
          ]
        },
        "media_type": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "image",
            "video",
            "carousel",
            "text"
          ]
        },
        "thumbnail_url": {
          "type": [
            "string",
            "null"
          ]
        },
        "video_url": {
          "type": [
            "string",
            "null"
          ]
        },
        "landing_url": {
          "type": [
            "string",
            "null"
          ]
        },
        "is_active": {
          "type": [
            "integer",
            "null"
          ],
          "enum": [
            0,
            1
          ]
        },
        "estimated_spend": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^-?[0-9]+(\\.[0-9]+)?$",
          "description": "Latest cumulative estimated spend in EUR. 0 can mean the estimate is unavailable. Decimal string."
        },
        "estimated_spend_eu": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^-?[0-9]+(\\.[0-9]+)?$",
          "description": "EU/UK part of the estimate in EUR. Decimal string."
        },
        "estimated_spend_usa": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^-?[0-9]+(\\.[0-9]+)?$",
          "description": "Extrapolated US part of the estimate in EUR. Decimal string."
        },
        "spend_coverage": {
          "type": "string",
          "enum": [
            "eu_uk",
            "eu_uk_us",
            "us_extrapolated",
            "none"
          ],
          "description": "Basis of the estimate: eu_uk is based on reach data that Meta publishes for the EU and UK; us_extrapolated and the US part of eu_uk_us are extrapolated; none means no estimate."
        },
        "spend_model_version": {
          "type": "integer"
        },
        "total_reach": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Reach that Meta publishes for the EU and UK."
        },
        "total_impressions": {
          "type": [
            "integer",
            "null"
          ]
        },
        "first_seen_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "Server timestamp, format YYYY-MM-DD HH:MM:SS."
        },
        "last_seen_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "Server timestamp, format YYYY-MM-DD HH:MM:SS."
        }
      }
    },
    "SpendMeta": {
      "type": "object",
      "description": "How to read the spend figures in this response.",
      "required": [
        "currency",
        "spend_basis",
        "model_version",
        "timeframe",
        "timeframe_basis",
        "period_spend_available",
        "zero_spend_means",
        "demographics_basis"
      ],
      "properties": {
        "currency": {
          "type": "string",
          "enum": [
            "EUR"
          ]
        },
        "spend_basis": {
          "type": "string",
          "enum": [
            "latest_cumulative_estimate"
          ]
        },
        "model_version": {
          "type": "integer"
        },
        "timeframe": {
          "type": "string",
          "enum": [
            "all",
            "7d",
            "30d",
            "90d"
          ],
          "description": "Last-seen filter that was applied; never a period-spend calculation."
        },
        "timeframe_basis": {
          "type": "string",
          "enum": [
            "last_seen_at"
          ]
        },
        "period_spend_available": {
          "type": "boolean",
          "enum": [
            false
          ]
        },
        "zero_spend_means": {
          "type": "string",
          "enum": [
            "unknown"
          ]
        },
        "demographics_basis": {
          "type": "string",
          "enum": [
            "latest_snapshot"
          ]
        },
        "sample_limit": {
          "type": "integer",
          "description": "Statistics only: creative breakdowns use at most this many top ads."
        },
        "sampled": {
          "type": "boolean",
          "description": "Statistics only: true when more ads matched than the sample holds."
        },
        "aggregate_scope": {
          "type": "string",
          "description": "Statistics only: which ads the matched totals cover."
        }
      }
    }
  }
}