/v2/advertisers/{advertiserId}/campaigns/{campaignId}/spa/ad-groups/search

POST

https://<pcm-domain>/v2/advertisers/{advertiserId}/campaigns/{campaignId}/spa/ad-groups/search

Retrieves filtered and paginated SPA ad groups for a campaign.

Rules:

The values array for the MODIFIED_AFTER filter must take exactly one value in the format yyyy-MM-dd'T'HH:mm
.SSS'Z' e.g. {"field":"MODIFIED_AFTER", "values":["2025-02-05T12:34
.000Z"]}.

Notes:

sortType defaults to ascending if not passed.

Path Parameters

advertiserIdinteger<int32>required
Format
int32
campaignIdinteger<int32>required
Format
int32

Body Parameters

bodySpaAdGroupSearchRequestrequired
- filtersFilterValuesSpaAdGroupFilterField[]
  - fieldstring<STATUS | AD_GROUP | MODIFIED_AFTER>
    Allowed
    STATUSAD_GROUPMODIFIED_AFTER
  - valuesobject[]
- pageinteger<int32>required
  Format
  int32
  Minimum
  0
  Maximum
  1000
- limitinteger<int32>required
  Format
  int32
  Minimum
  1
  Maximum
  10000
- sortTypestring<ASC | DESC>
  Allowed
  ASCDESC
- orderBystring<AD_GROUP | STATUS | MARKET | BUDGET | BUDGET_SPENT | SPEND_VELOCITY | START_DATE | END_DATE | PUBLISHER>required
  Allowed
  AD_GROUPSTATUSMARKETBUDGETBUDGET_SPENTSPEND_VELOCITYSTART_DATEEND_DATEPUBLISHER

Responses

200OK

ListResponseSpaAdGroupResponseVoid
- detailedSpaAdGroupResponse[]
  - idinteger<int32>
    Format
    int32
  - publisherPublisherWithGlobalFloorPriceResponse
    - idinteger<int32>
      Format
      int32
    - namestring
    - bidBelowGlobalFloorPriceboolean
  - namestring
  - typestring<DISPLAY | SPA | SPONSORED_BRAND>
    Allowed
    DISPLAYSPASPONSORED_BRAND
  - statusstring<ARCHIVED | EXPIRED | LIVE | PAUSED | SCHEDULED | WAITING | REJECTED>
    Allowed
    ARCHIVEDEXPIREDLIVEPAUSEDSCHEDULEDWAITINGREJECTED
  - budgetnumber
  - budgetSpentnumber
  - dailyBudgetnumber
  - weeklyBudgetnumber
  - monthlyBudgetnumber
  - useDynamicBudgetboolean
    Description
    Whenever dynamic budget is activated daily limits are calculated in order that the remaining budget is evenly distributed over the ad group's lifetime.
  - dailySpendPacingstring<ASAP | EVEN>
    Allowed
    ASAPEVEN
  - spendVelocitynumber<double>
    Description
    The pacing of the ad group measures budget efficiency over time, where a value of 1.0 reflects ideal spend considering temporal progress of the ad group, less than 1.0 underspending, and more than 1.0 overspending. The value is not set whenever the ad group has no end date.
    Format
    double
  - startDatestring<date-time>
    Format
    date-time
  - endDatestring<date-time>
    Format
    date-time
  - targetedSiteIdsinteger[]
  - targetedLocationsAdGroupTargetLocation[]
    - locationstring<CATEGORY_PAGE | SEARCH_PAGE | HOME_PAGE | PRODUCT_PAGE | CHECKOUT | MINI_SEARCH | EMAIL | EMAIL_ABANDONED_CART>
      Allowed
      CATEGORY_PAGESEARCH_PAGEHOME_PAGEPRODUCT_PAGECHECKOUTMINI_SEARCHEMAILEMAIL_ABANDONED_CART
    - pagePositionstring<MAIN_GRID | CAROUSEL | BELOW_THE_FOLD | ABOVE_THE_FOLD | L1 | L2 | L3 | L4>
      Allowed
      MAIN_GRIDCAROUSELBELOW_THE_FOLDABOVE_THE_FOLDL1L2L3L4
  - advertisedboolean
  - globalFloorPricenumber
  - modifiedAtstring<date-time>
    Format
    date-time
- aggregatedAggregatedVoid
  - countinteger<int64>
    Format
    int64
  - metrics

401Unauthorized

403Forbidden

404Not Found

ExceptionResponse
- messagesstring[]

422Unprocessable Entity

ExceptionResponse
- messagesstring[]

curl

curl --request POST \
     --url https://<pcm-domain>/v2/advertisers/{advertiserId}/campaigns/{campaignId}/spa/ad-groups/search \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
     "page": 0,
     "limit": 0,
     "orderBy": ""
     }'

javascript

var myHeaders = new Headers();
myHeaders.append("accept", "application/json");
myHeaders.append("content-type", "application/json");

var raw = JSON.stringify({
   "page": 0,
   "limit": 0,
   "orderBy": ""
});

var requestOptions = {
   method: 'POST',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch("https://<pcm-domain>/v2/advertisers/{advertiserId}/campaigns/{campaignId}/spa/ad-groups/search", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

ruby

require "uri"
require "json"
require "net/http"

url = URI("https://<pcm-domain>/v2/advertisers/{advertiserId}/campaigns/{campaignId}/spa/ad-groups/search")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["accept"] = "application/json"
request["content-type"] = "application/json"
request.body = JSON.dump({
   "page": 0,
   "limit": 0,
   "orderBy": ""
})

response = https.request(request)
puts response.read_body

python

import requests
import json

url = "https://<pcm-domain>/v2/advertisers/{advertiserId}/campaigns/{campaignId}/spa/ad-groups/search"

payload = json.dumps({
   "page": 0,
   "limit": 0,
   "orderBy": ""
})
headers = {
   'accept': 'application/json',
   'content-type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

200

// OK
{
  "detailed": [
    {
      "id": "",
      "publisher": {
        "id": "",
        "name": "",
        "bidBelowGlobalFloorPrice": false
      },
      "name": "",
      "type": "",
      "status": "",
      "budget": 0,
      "budgetSpent": 0,
      "dailyBudget": 0,
      "weeklyBudget": 0,
      "monthlyBudget": 0,
      "useDynamicBudget": false,
      "dailySpendPacing": "",
      "spendVelocity": "",
      "startDate": "",
      "endDate": "",
      "targetedSiteIds": [
        0
      ],
      "targetedLocations": [
        {
          "location": "",
          "pagePosition": ""
        }
      ],
      "advertised": false,
      "globalFloorPrice": 0,
      "modifiedAt": ""
    }
  ],
  "aggregated": {
    "count": "",
    "metrics": ""
  }
}

401

// Unauthorized

403

// Forbidden

404

// Not Found
{
  "messages": [
    ""
  ]
}

422

// Unprocessable Entity
{
  "messages": [
    ""
  ]
}