---
title: "Get Domain Ad History by Date"
method: GET
path: "/v2/domain/getDomainAdHistoryByDate"
tags: ["Ad History Research API"]
---

# Get Domain Ad History by Date

`GET /v2/domain/getDomainAdHistoryByDate`

Returns one row per keyword, search date, and ad variation for a domain. Use the date bounds and paging fields to pull a controlled slice while still seeing the total matching result size.

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

## Query parameters

- `domain` string, required
- `keywordFilter` string
- `minSearchDateId` integer
- `maxSearchDateId` integer
- `startingRow` integer
- `pageSize` integer
- `keywordStartingRow` integer
- `keywordPageSize` integer
- `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'

## Response `200`

Successfully retrieved flattened domain ad history rows and result-size metadata for the requested date range.

- object — Response wrapper containing flattened domain ad history rows with paging and full-match metadata.
  - `totalMatchingResults` integer — Total flattened keyword/date/ad rows found in the fetched keyword window after the date and keyword filters are applied.
  - `totalMatchingResultsIsPartial` boolean — True when more keyword/domain documents exist outside this response's backing query window, so totalMatchingResults is only the flattened count for this keyword window.
  - `resultCount` integer — Number of flattened keyword/date/ad rows returned in this response.
  - `startingRow` integer — Starting row number used for this page.
  - `pageSize` integer — Requested maximum number of rows returned in this page.
  - `hasMoreResults` boolean — True when more flattened rows are available after this page.
  - `totalMatchingKeywords` integer, nullable — Total keyword/domain documents matched by the backing query before flattening date rows.
  - `keywordStartingRow` integer — Keyword/domain document row number used to start the backing query.
  - `keywordPageSize` integer — Requested maximum number of keyword/domain documents fetched by the backing query.
  - `resultWindowKeywordCount` integer — Number of keyword/domain documents returned by the backing query for this response.
  - `hasMoreKeywordResults` boolean — True when more keyword/domain documents are available after this backing query window.
  - `results` object[], nullable — Flattened keyword/date/ad rows for the requested page.
    - `keyword` string, nullable — Keyword that triggered this ad for the requested domain.
    - `termId` integer — Internal SpyFu identifier for the keyword.
    - `searchDateId` integer — Date when this ad was captured by SpyFu's crawling system, formatted as YYYYMMDD (e.g., 20240101 = January 1, 2024).
    - `position` integer — Paid ad position observed for this ad on the search results page.
    - `title` string, nullable — Headline text used in the ad.
    - `body` string, nullable — Body copy used in the ad.
    - `domainName` string, nullable — Advertiser domain that served the ad.
    - `fullUrl` string, nullable — Full final destination URL captured for this ad variation.
    - `adId` integer — SpyFu identifier for the ad creative.
    - `isLeaderboardAd` boolean — Whether this ad was observed in a leaderboard placement.

## Other responses

- `400` — Bad Request - Invalid parameters provided (e.g., invalid date bounds, 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.net/spyfu/apis/domain-stats-api.md) · [All operations](https://skmtc.net/spyfu/apis/domain-stats-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/spyfu/domain-stats-api/revisions/44f0aff08ed0/schema)