Foreplay API icon

Foreplay API

Interact with the Foreplay API

Actions13

Overview

This node integrates with the Foreplay API to retrieve advertising data. Specifically, the "Get Ads by Page ID" operation fetches ads associated with a given Facebook page ID. This is useful for marketers, advertisers, or analysts who want to monitor or analyze ad campaigns run by specific pages.

Common scenarios include:

  • Tracking competitor ads on a particular Facebook page.
  • Gathering data for market research or ad performance analysis.
  • Automating reports on active or historical ads linked to a page.

For example, you can input a Facebook page ID and filter ads by date range, live status, display format, publisher platform, niches, languages, and more to get targeted ad data.

Properties

Name Meaning
Page ID The unique identifier of the Facebook page whose ads you want to retrieve. (Required)
Start Date The start date (inclusive) to filter ads from. Accepts formats like YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS, or YYYY-MM-DD HH:MM:SS.
End Date The end date (inclusive) to filter ads until. Same accepted formats as Start Date.
Live Status Filter ads based on whether they are currently live (active). Options: All, Live (Active), Not Live.
Display Format Filter ads by one or more display formats such as Carousel, DCO, DPA, Event, Image, Multi Images, Multi Medias, Multi Videos, Page Like, Text, Video.
Publisher Platform Filter ads by one or more platforms where they were published, e.g., Audience Network, Facebook, Instagram, LinkedIn, Messenger, Threads, TikTok, YouTube.
Niches Filter ads by one or more niches/categories like Accessories, App/Software, Beauty, Business/Professional, Education, Entertainment, Fashion, Food/Drink, Health/Wellness, Home/Garden, Jewelry/Watches, Other, Parenting, Pets, Real Estate, Service Business.
Market Target Filter ads by market target: B2B or B2C.
Languages Filter ads by language(s) such as Dutch/Flemish, English, French, German, Italian, Japanese, Latvian, Lithuanian, Polish, Portuguese, Romanian/Moldavian/Moldovan, Serbian, Slovene, Spanish/Castilian, Swedish.
Cursor A cursor string used for pagination to fetch subsequent pages of results.
Limit Maximum number of results to return. Minimum value is 1. Default is 5.
Order Order in which results are returned. Options: Newest, Oldest, Longest Running, Most Relevant.

Output

The node outputs an array of JSON objects under the json field. Each object contains the response from the Foreplay API for the requested ads. The structure typically includes details about each ad such as its content, status, targeting, metrics, and metadata.

If binary data is present (not explicitly shown in this operation), it would represent media assets related to ads (images, videos).

Example output snippet (conceptual):

[
  {
    "response": {
      "ads": [
        {
          "id": "12345",
          "pageId": "67890",
          "status": "active",
          "startDate": "2024-01-01",
          "endDate": "2024-02-01",
          "format": "video",
          "platform": "facebook",
          "metrics": { ... },
          ...
        }
      ],
      "pagination": {
        "cursor": "abc123"
      }
    }
  }
]

Dependencies

  • Requires an API key credential for the Foreplay API.
  • The base URL for the API must be configured in the node credentials.
  • The node uses HTTP requests authenticated via the provided API key.
  • No other external dependencies are required.

Troubleshooting

  • Invalid Operation Error: If the operation name is incorrect or not supported, the node will throw an "Invalid operation" error. Ensure the operation parameter is set exactly to "getAdsByPageId".
  • Authentication Errors: If the API key or base URL is missing or invalid, authentication will fail. Verify that the Foreplay API credentials are correctly configured.
  • Empty Results: If no ads are returned, check filters such as date range, live status, or page ID correctness.
  • Pagination Issues: When using the cursor for pagination, ensure the cursor value is valid and corresponds to the previous response.
  • Rate Limits: The Foreplay API may enforce rate limits; if exceeded, requests might fail temporarily.

Links and References

Discussion