---
title: "Get Keyword Ad History With Stats"
method: GET
path: "/v2/term/getTermAdHistoryWithStats"
tags: ["Ad History Research API"]
---

# Get Keyword Ad History With Stats

`GET /v2/term/getTermAdHistoryWithStats`

## Request

- Base URL: `https://api.spyfu.com/apis/cloud_ad_history_api`
- URL: `https://api.spyfu.com/apis/cloud_ad_history_api/v2/term/getTermAdHistoryWithStats`
- Auth: one of:
  - HTTP basic
  - API key in query parameter `api_key`
  - API key in header `Authentication`

Returns historical ad variations and advertiser performance statistics for a specific keyword. This endpoint includes domain-level metrics alongside ad copy data, unlike the basic ad history endpoint that focuses purely on ad variations.

[Visualize this API live on SpyFu](https://www.spyfu.com/keyword/ad-history?query=example%20keyword)

## Query parameters

- `term` string, required
- `countryCode` 'AR' | 'AT' | 'AU' | 'BE' | 'BR' | 'CA' | 'CH' | 'DE' | 'DK' | 'ES' | 'FR' | 'IE' | 'IN' | 'IT' | 'JP' | 'MX' | 'NL' | 'NO' | 'NZ' | 'PL' | 'PT' | 'SE' | 'SG' | 'TR' | 'UA' | 'UK' | 'US' | 'ZA'
- `pageSize` integer
- `startingRow` integer

## Response `200`

Successfully retrieved ad history data with advertiser statistics for the specified keyword. Returns a paginated list of ads with performance metrics and domain-level data.

- object: Response wrapper containing comprehensive term ad history statistics including advertiser analysis and top-performing ads.
  - `resultCount` integer: Number of results returned
  - `domains` object[], nullable: Array of domains (advertisers) that have purchased ads for the specified keyword, ranked by performance metrics.
    - `ads` object[], nullable: Collection of ads this domain has purchased for the specified keyword.
      - `searchDateId` integer: Date when this ad was captured by SpyFu's crawling system, formatted as YYYYMMDD (e.g., 20231215 = December 15, 2023).
      - `position` integer: The ad's position on the search results page when it was captured (1 = top position).
      - `title` string, nullable: The headline text of the ad as it appeared in search results.
      - `body` string, nullable: The description text of the ad providing additional details about the offer.
      - `domainName` string, nullable: The domain name of the advertiser who placed this ad.
      - `fullUrl` string, nullable: The complete landing page URL that the ad directed users to when clicked.
      - `term` string, nullable: The search keyword that triggered this ad to appear in search results.
      - `adCount` integer: The number of times this specific ad variation was observed during the capture period.
      - `isLeaderboardAd` boolean: Indicates whether this ad appeared in the top ad positions (leaderboard) rather than sidebar positions.
    - `budget` number, double: Estimated monthly advertising budget this domain spends on the specified keyword.
    - `coverage` number, double: Percentage of time this domain appears in ads for the specified keyword (0-100).
    - `domainName` string, nullable: The domain name of the advertiser.
    - `percentageLeaderboard` number, double: Percentage of time this domain's ads appear in top positions (leaderboard) rather than sidebar positions.
    - `totalAdsPurchased` integer: Total number of ads this domain has purchased across all keywords in SpyFu's database.
    - `adCount` integer: Number of ads this domain has purchased specifically for the requested keyword.
  - `topAds` object[], nullable: Array of the most successful ads for the specified keyword, ranked by performance and frequency metrics.
    - `adId` integer: Unique identifier for this specific ad in SpyFu's database.
    - `averagePosition` number, double: Average position where this ad appeared on search results pages across all observations.
    - `averageAdCount` number, double: Average total number of ads per capture period.
    - `body` string, nullable: The description text of the ad providing additional details about the offer.
    - `title` string, nullable: The headline text of the ad as it appeared in search results.
    - `fullUrl` string, nullable: The complete landing page URL that the ad directed users to when clicked.
    - `leaderboardCount` integer: Number of times this ad appeared in top ad positions (leaderboard) rather than sidebar positions.
    - `percentageLeaderboard` number, double: Percentage of time this ad appeared in top ad positions versus sidebar positions.
    - `percentageAdsServed` number, double: Percentage of total ad impressions this specific ad variation represented for the advertiser.

## Other responses

- `400`: Bad Request - Invalid parameters provided (e.g., empty term, pageSize exceeds maximum, or invalid country code)
- `401`: Unauthorized - Invalid API credentials or insufficient permissions to access ad history data
- `500`: Internal Server Error - A server-side error occurred while processing the request

---

[API](https://skmtc.dev/spyfu/apis/ad-history-api.md) - [All operations](https://skmtc.dev/spyfu/apis/ad-history-api/llms.txt) - [OpenAPI document](https://skmtc.dev/spyfu/apis/ad-history-api/revisions/bc314568ac41?raw)