Documentation for getCampaigns

Overview

This node in the Vantage analytics platform is designed to fetch advertising campaign details from a specified ad account. Utilizing integrations with advertising APIs, this function collects information about the campaigns, such as their identifiers, statuses, budgets, and timing, allowing users to analyze and manage their advertising strategies effectively. The flexibility provided by the customizable input parameters enables tailored API requests to suit various business needs.

Settings

This node has several settings that dictate its behavior and output. Below are detailed descriptions of each setting:

1. Ad Account ID (adAccountId)

• Input Type: String
• Description: The adAccountId is the unique identifier for the advertising account from which campaigns are to be retrieved. This setting is crucial as it specifies the account context for which the campaigns will be fetched. Leaving this field empty will result in an error, indicating that the Ad Account ID is required.
• Default Value: '' (empty string)

2. Fields (fields)

• Input Type: String
• Description: The fields setting determines which attributes of the campaigns will be included in the response. By default, it requests a set of common properties (id, name, status, objective, daily_budget, lifetime_budget, start_time, stop_time, created_time, updated_time). Modifying this setting allows for more precise data responses, improving performance by limiting the payload size.
• Default Value: 'id,name,status,objective,daily_budget,lifetime_budget,start_time,stop_time,created_time,updated_time'

3. Limit (limit)

• Input Type: Numeric
• Description: The limit setting controls the number of campaign entries returned in the response. Setting a lower limit allows for faster responses but may not provide a complete view of all campaigns. The maximum size should adhere to the API's constraints, which is typically configurable.
• Default Value: 50

4. Effective Status (effectiveStatus)

• Input Type: String
• Description: This setting specifies the operational status filter for the campaigns. It allows users to limit the results to campaigns that are in a specific effective status (e.g., ACTIVE, PAUSED, etc.). If left blank, all campaigns, regardless of their status, will be retrieved.
• Default Value: '' (empty string)

How It Works

The node begins by inspecting the input parameters and using them to ascertain relevant configurations. If the adAccountId isn't provided, it immediately returns an error, ensuring that necessary identification is always supplied.

Once the inputs are confirmed, the function utilizes the integration connection to establish a connection with the Meta Marketing API through context provided by the user. The core of the function is making the getCampaigns API call, where it sends the specified adAccountId, selected fields, limit, and effectiveStatus. The retrieved data is processed and returned as output.

In cases of an error, whether during connection establishment or the API call, an appropriate error message is returned, allowing for easier troubleshooting.

Data Expectations

• Input Data: The function expects an object containing inputs, config, and context parameters. Essential among these is adAccountId, while others like fields, limit, and effectiveStatus are optional.
• Output Data: The output consists of:
  • output1: An object containing a data array of campaign details and paging information if applicable.
  • An error object if the API call fails or if required parameters are missing.

Use Cases & Examples

Use Cases

1. Campaign Performance Monitoring: A marketing team may need to regularly track the status and performance of their advertising campaigns to make data-driven adjustments to their strategies.

2. Budget Management: An analyst requires information on the daily and lifetime budgets of various campaigns to ensure that spending aligns with budget forecasts and strategy.

3. Campaign Lifecycle Management: A product manager wants to analyze campaigns that are not performing well by identifying those that are paused or inactive, allowing for timely decisions regarding campaign adjustments.

Example Configuration

Use Case – Campaign Performance Monitoring: Suppose a digital marketing agency wants to monitor all active campaigns within a specific ad account to evaluate their performance.

Configured Settings:

{
    inputs: {
        adAccountId: 'act_123456789',
        fields: 'id,name,status,daily_budget,lifetime_budget,start_time,stop_time',
        limit: 100,
        effectiveStatus: 'ACTIVE'
    },
    config: {},
    context: userContext
}

In this configuration:

• adAccountId: Represents the target advertising account.
• fields: Specifies to fetch campaign ID, name, status, daily budget, lifetime budget, start time, and stop time.
• limit: Has been set to 100 to retrieve a larger set of campaigns for thorough analysis.
• effectiveStatus: Filters results to only include campaigns that are currently active.

This setup ensures that the marketing agency can receive detailed insights into their active campaigns swiftly and effectively for ongoing performance evaluations.