Actions13
Overview
This node integrates with the Foreplay API to retrieve advertising data based on specified criteria. The "Get Ads by Brand ID" operation allows users to fetch ads associated with one or more brand IDs, optionally filtered by date range, live status, display format, publisher platform, niches, market target, languages, and pagination controls.
Typical use cases include:
- Monitoring ad campaigns for specific brands.
- Analyzing ad performance over a given time period.
- Filtering ads by format or platform to tailor marketing insights.
- Collecting competitive intelligence on brand advertisements.
For example, a marketing analyst could use this node to pull all active carousel ads from Facebook and Instagram for a set of brand IDs within the last month to evaluate campaign effectiveness.
Properties
| Name | Meaning |
|---|---|
| Brand IDs | Brand ID(s) to search for. Can be a single ID or multiple IDs separated by commas. (Required) |
| Start Date | Start date (inclusive) filter for ads. Accepts formats like YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS, or YYYY-MM-DD HH:MM:SS. |
| End Date | End date (inclusive) filter for ads. Same accepted formats as Start Date. |
| Live Status | Filter ads by live status. Options: All, Live (Active), Not Live. |
| Display Format | Filter by one or more ad display formats. Options include Carousel, DCO, DPA, Event, Image, Multi Images, Multi Medias, Multi Videos, Page Like, Text, Video. |
| Publisher Platform | Filter by one or more publisher platforms. Options include Audience Network, Facebook, Instagram, LinkedIn, Messenger, Threads, TikTok, YouTube. |
| Niches | Filter by one or more niches/categories. Options include 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 by market target. Options: B2B, B2C. |
| Languages | Filter by languages. Options include Dutch/Flemish, English, French, German, Italian, Japanese, Latvian, Lithuanian, Polish, Portuguese, Romanian/Moldavian/Moldovan, Serbian, Slovene, Spanish/Castilian, Swedish. |
| Cursor | Cursor string for pagination to fetch subsequent pages of results. |
| Limit | Maximum number of results to return. Minimum value is 1. Default is 5. |
| Order | Order of results. Options: Newest, Oldest, Longest Running, Most Relevant. Default is Newest. |
Output
The node outputs an array of JSON objects under the json field. Each object contains the response from the Foreplay API corresponding to the requested ads matching the input filters.
The structure typically includes details about each ad such as its ID, brand association, creative format, live status, publishing platform, niche, language, dates, and other metadata as provided by the API.
If the API supports binary data (e.g., images or videos related to ads), the node would handle it accordingly, but based on the static code analysis, the output focuses on JSON responses containing ad data.
Dependencies
- Requires an API key credential for authenticating with the Foreplay API.
- The base URL for the API must be configured in the node credentials.
- The node uses HTTP requests with authentication to communicate with the Foreplay API endpoints.
Troubleshooting
- Invalid Operation Error: If the operation name does not match any known endpoint, the node throws an "Invalid operation" error. Ensure the operation parameter is correctly set to "getAdsByBrandId".
- Authentication Failures: Errors related to authentication usually indicate missing or invalid API credentials. Verify that the API key and base URL are correctly configured.
- Empty Results: If no ads are returned, check the correctness of brand IDs, date ranges, and filters. Also, verify that the brand IDs exist and have ads in the Foreplay system.
- Pagination Issues: When using the cursor for pagination, ensure the cursor value is valid and corresponds to the previous response's pagination token.
- Rate Limits or API Errors: The API may return errors due to rate limits or server issues. Implement retry logic or check API usage quotas if applicable.
Links and References
- Foreplay API Documentation (Assumed link; replace with actual if available)
- n8n HTTP Request Node Documentation: https://docs.n8n.io/nodes/n8n-nodes-base.httpRequest/
- General n8n Credential Setup Guide: https://docs.n8n.io/credentials/overview/