Fetch bulk posts for a location — Listings API

Parameters

Path

Name	Type	Required	Description
locationId	string	required	Base64-encoded location cursor / global ID (e.g. `TG9jYXRpb246MTgwMDI4OQ==`). Pass it verbatim, do not URL-encode it. The base64 cursor always resolves; the raw numeric database ID also works on this endpoint, but the base64 form is the portable choice across the API.

Query

Name	Type	Required	Description	Default
tag	string	required	Segment/tag to pull campaigns from. Pass `all` to fetch every bulk campaign touching the location. Omitting this returns an error, not an empty list.	—
page	integer	optional	1-based page number for offset pagination.	1
perPage	integer	optional	Number of records per page.	—
filters	string	optional	JSON-encoded SocialPostFiltersInput (e.g. by `type`, `status`, `creationDateRange`, `siteUrls`).	—
sortFields	string	optional	JSON-encoded sort object `{ "field": "created_at", "order": "Descending" }`. `field` is one of name, type, status, created_at, schedule_start_date, schedule_end_date, client_name, clicks, views, shares.	—
locationIds	string	optional	JSON-encoded array of location IDs to include alongside the path location.	—
componentIdentifier	string	optional	Filter to campaigns created by a specific component/integration.	—

Responses

200A page of bulk campaigns that include the location. `records` is empty when no bulk campaign has targeted it.

{
  "data": {
    "rollupSocialPosts": {
      "records": [
        {
          "id": "U29jaWFsUG9zdDo1MTA4OA==",
          "name": "Diwali Offer - All Stores",
          "status": "SUCCESS",
          "type": "OFFER",
          "createdAt": "2026-06-20",
          "scheduledStartDate": "2026-06-22",
          "scheduledEndDate": "2026-07-06",
          "views": 4210,
          "clicks": 318,
          "shares": 12,
          "reactions": 87,
          "comments": 4,
          "sites": ["GOOGLE", "FACEBOOK"],
          "message": [
            { "site": "GOOGLE", "message": "Festive savings across all our stores this week." },
            { "site": "FACEBOOK", "message": "Festive savings across all our stores this week!" }
          ],
          "cta": [
            { "type": { "value": "GET_OFFER", "label": "Get offer" }, "url": "https://jennyhome.example/diwali", "site": "GOOGLE", "tinyUrl": "https://tiny.cc/jh-diwali" }
          ],
          "contextInfo": {
            "couponCode": "DIWALI25",
            "redeemUrl": "https://jennyhome.example/diwali",
            "termsConditions": "Valid in-store only. Cannot be combined with other offers.",
            "title": "25% off storewide",
            "discount": "25%",
            "startDay": "2026-06-22",
            "endDay": "2026-07-06"
          },
          "mediaUrl": [
            { "url": "https://cdn.listingsapi.com/posts/51088/diwali.jpg", "site": "GOOGLE", "type": "IMAGE" }
          ],
          "publishDetails": [
            { "site": "GOOGLE", "status": "PUBLISHED", "createdDate": "2026-06-20", "publishedDate": "2026-06-22", "submissionError": null },
            { "site": "FACEBOOK", "status": "PUBLISHED", "createdDate": "2026-06-20", "publishedDate": "2026-06-22", "submissionError": null }
          ],
          "postLinks": [
            { "site": "GOOGLE", "link": "https://www.google.com/maps/place/?post=51088" }
          ],
          "locationIds": [1800289, 1800290, 1800291],
          "clientName": "Jenny Home"
        }
      ],
      "locationDetails": [
        {
          "id": "TG9jYXRpb246MTgwMDI4OQ==",
          "name": "Jenny Home",
          "street": "600 Congress Ave, Suite 200",
          "city": "Austin",
          "postalCode": "78701",
          "countryIso": "US",
          "stateIso": "TX",
          "stateName": "Texas",
          "storeId": null
        }
      ],
      "pageInfo": {
        "totalPages": 1,
        "hasNextPage": false,
        "hasPreviousPage": false,
        "totalRecords": 1
      }
    }
  }
}

401Unauthenticated, missing or invalid API key.

429Rate limit exceeded. Retry after the `Retry-After` header value.

A bulk post is one campaign published to many locations at once (created via POST /bulk-posts). This endpoint lists the bulk campaigns that include the given location, so you can see multi-store rollups from a single store's perspective. The response shape is identical to GET /locations/{locationId}/posts; records here simply span multiple locationIds.

Use case: reconcile a chain-wide rollout. After launching a "Diwali Offer" across every store, call GET /locations/1800289/bulk-posts?tag=all from any one store to confirm the campaign reached it, inspect the shared contextInfo (coupon code, discount, terms), and read the per-site publishDetails to spot a FACEBOOK submissionError on that location.

Gotchas.

Same as the single-location list: tag is effectively required (use tag=all), pagination is offset-based via page/perPage, sortFields is a single object (not an array), and heavy polling can return HTTP 429.
locationIds on each record is the full set the campaign targeted, it will contain IDs beyond the one in the path.

The records array above is representative. The live seed location (Jenny Home) has no bulk campaigns, so a real call returns records: [] with pageInfo.totalRecords: 0.