meta-ads-mcp

get_campaign_by_id

Retrieve detailed Facebook ad campaign data by campaign ID, including objective, status, budgets, and configuration. Use this to inspect or audit a specific campaign's settings.

Instructions

Retrieves detailed information about a specific Facebook ad campaign by its ID.

This function accesses the Facebook Graph API to retrieve information about a single campaign, including details about its objective, status, budget settings, and other campaign-level configurations.

Args: campaign_id (str): The ID of the campaign to retrieve information for. fields (Optional[List[str]]): A list of specific fields to retrieve. If None, a default set of fields will be returned. Available fields include: - 'id': The campaign's ID - 'name': The campaign's name - 'account_id': The ID of the ad account this campaign belongs to - 'adlabels': Labels applied to the campaign - 'bid_strategy': The bid strategy for the campaign. Options include: 'LOWEST_COST_WITHOUT_CAP', 'LOWEST_COST_WITH_BID_CAP', 'COST_CAP' - 'boosted_object_id': The ID of the boosted object - 'brand_lift_studies': Brand lift studies associated with this campaign - 'budget_rebalance_flag': Whether budget rebalancing is enabled - 'budget_remaining': The remaining budget (in cents/smallest currency unit) - 'buying_type': The buying type. Options include: 'AUCTION', 'RESERVED', 'DEPRECATED_REACH_BLOCK' - 'can_create_brand_lift_study': Whether a brand lift study can be created - 'can_use_spend_cap': Whether a spend cap can be used - 'configured_status': Status set by the user. Options include: 'ACTIVE', 'PAUSED', 'DELETED', 'ARCHIVED' - 'created_time': When the campaign was created - 'daily_budget': The daily budget (in cents/smallest currency unit) - 'effective_status': The effective status accounting for the ad account and other factors. Options include: 'ACTIVE', 'PAUSED', 'DELETED', 'PENDING_REVIEW', 'DISAPPROVED', 'PREAPPROVED', 'PENDING_BILLING_INFO', 'CAMPAIGN_PAUSED', 'ARCHIVED', 'IN_PROCESS', 'WITH_ISSUES' - 'has_secondary_skadnetwork_reporting': Whether secondary SKAdNetwork reporting is available - 'is_budget_schedule_enabled': Whether budget scheduling is enabled - 'is_skadnetwork_attribution': Whether the campaign uses SKAdNetwork attribution (iOS 14.5+) - 'issues_info': Information about issues with this campaign - 'last_budget_toggling_time': Last time the budget was toggled - 'lifetime_budget': The lifetime budget (in cents/smallest currency unit) - 'objective': The campaign's advertising objective. Options include: 'APP_INSTALLS', 'BRAND_AWARENESS', 'CONVERSIONS', 'EVENT_RESPONSES', 'LEAD_GENERATION', 'LINK_CLICKS', 'LOCAL_AWARENESS', 'MESSAGES', 'OFFER_CLAIMS', 'PAGE_LIKES', 'POST_ENGAGEMENT', 'PRODUCT_CATALOG_SALES', 'REACH', 'STORE_VISITS', 'VIDEO_VIEWS' - 'pacing_type': List of pacing types. Options include: 'standard', 'no_pacing' - 'primary_attribution': Primary attribution settings - 'promoted_object': The object this campaign is promoting - 'recommendations': Recommendations for improving this campaign - 'smart_promotion_type': Smart promotion type if applicable - 'source_campaign': Source campaign if this was created by copying - 'source_campaign_id': ID of the source campaign if copied - 'special_ad_categories': Array of special ad categories. Options include: 'EMPLOYMENT', 'HOUSING', 'CREDIT', 'ISSUES_ELECTIONS_POLITICS', 'NONE' - 'special_ad_category': Special ad category (deprecated in favor of special_ad_categories) - 'spend_cap': The spending cap (in cents/smallest currency unit) - 'start_time': When the campaign starts (in ISO 8601 format unless date_format specified) - 'status': Deprecated. Use 'configured_status' or 'effective_status' instead - 'stop_time': When the campaign stops (in ISO 8601 format unless date_format specified) - 'topline_id': Topline ID for this campaign - 'updated_time': When this campaign was last updated date_format (Optional[str]): Format for date responses. Options: - 'U': Unix timestamp (seconds since epoch) - 'Y-m-d H:i:s': MySQL datetime format - None: ISO 8601 format (default)

Returns: Dict: A dictionary containing the requested campaign information.

Example: ```python # Get basic campaign information campaign = get_campaign_by_id( campaign_id="23843211234567", fields=["name", "objective", "effective_status", "budget_remaining"] )

# Get detailed budget information with Unix timestamps
campaign_budget_details = get_campaign_by_id(
    campaign_id="23843211234567",
    fields=["name", "daily_budget", "lifetime_budget", "start_time", "stop_time"],
    date_format="U"
)
```

Input Schema

TableJSON Schema

Name	Required	Description	Default
`fields`	No
`campaign_id`	Yes
`date_format`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 21, 2026

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states the tool 'retrieves' information via the Facebook Graph API, implying a read-only operation with no side effects. It also details how fields and date_format affect output, including default behaviors. It does not mention error handling or rate limits, but for a straightforward GET operation this is acceptable; the description is transparent about what the tool does and does not do.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long, but it is well-structured with a purpose statement, Args section, Returns note, and a full example. The extensive field enumeration is justified because the schema provides no descriptions, making it essential for correct field selection. Every section serves a purpose, and the organization makes it easy to scan. It is appropriately thorough rather than bloated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (many optional fields and a date format option), the description is complete. It covers all parameters, their defaults, allowed values, and gives a concrete example. Since an output schema exists, it does not need to describe the return structure beyond stating it returns a dict. No critical information for invoking the tool correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate fully. It does: it explains every parameter in detail—campaign_id with its role, fields with a comprehensive list of valid values and their meaning, and date_format with all allowed formats. Examples further clarify usage. This is far beyond minimal and gives an agent everything needed to construct correct arguments.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Retrieves detailed information about a specific Facebook ad campaign by its ID.' This clearly states the tool's function and distinguishes it from sibling tools like get_ad_by_id or get_adset_by_id, which target different entities. The purpose is immediately actionable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

While the description does not explicitly list when to use this tool over alternatives, it imposes clear context: this is for a single campaign identified by ID, which naturally separates it from tools that list campaigns or handle other entities. The absence of exclusions or direct sibling comparisons is compensated by the specificity of the function name and description, giving an agent sufficient guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server