Meta Ads by Get MCP Ads

meta get insights raw

meta_get_insights_raw

Read-onlyIdempotent

Query Meta Insights with native fields, breakdowns, filters, attribution windows, sorting, and pagination to report on new metrics before the curated catalog updates.

Instructions

Query the Meta Insights edge with validated native field names, breakdowns, action breakdowns, attribution windows, filters, sort, summary, and pagination. This complements meta_get_insights when Meta adds fields before the curated metric catalog is updated.

Input Schema

Name	Required	Description
`sort`	No	Native provider ordering expressions.
`after`	No	Opaque cursor for the next page returned by Meta.
`level`	No	Entity or aggregation level for the requested report.
`limit`	No	Maximum number of returned items or rows. The declared bounds and default apply; use pagination for additional results.
`fields`	Yes	Native Meta Insights API fields; calculated aliases are not accepted here
`objectId`	Yes	Ad account (act_...), campaign, ad set, or ad ID whose /insights edge should be queried
`filtering`	No	Native provider filter expressions; credentials and account overrides are not allowed.
`timeRange`	No	Explicit provider reporting period with since and until dates.
`breakdowns`	No	Native reporting breakdowns. Check compatibility before combining them.
`datePreset`	No	Named reporting period. Use the custom date range when you need exact start and end dates.
`timeIncrement`	No	Provider time-bucket size or supported aggregate value.
`includeSummary`	No	Request the provider's available summary or total-count metadata.
`actionBreakdowns`	No	Meta action-level breakdowns, subject to Insights compatibility rules.
`actionAttributionWindows`	No	Meta attribution windows used to attribute action metrics.

Output Schema

Name	Required	Description	Default
`result`	Yes	Original tool result: parsed JSON when the text is JSON, otherwise the text or multiple MCP content blocks. Provider fields depend on the selected query.

Schema Changelog

Changes observed during successful MCP inspections.

Changed17 schema fields changedv2.1.1Oct 30, 2026
- removedInput schema / additionalProperties
```
Removed value: -false
```
- removedInput schema / properties / actionBreakdowns / items / $ref
```
Removed value: -"#/properties/fields/items"
```
- addedInput schema / properties / actionBreakdowns / items / maxLength
```
Added value: +100
```
- addedInput schema / properties / actionBreakdowns / items / minLength
```
Added value: +1
```
- addedInput schema / properties / actionBreakdowns / items / pattern
```
Added value: +"^[A-Za-z][A-Za-z0-9_]*$"
```
- addedInput schema / properties / actionBreakdowns / items / type
```
Added value: +"string"
```
- removedInput schema / properties / breakdowns / items / $ref
```
Removed value: -"#/properties/fields/items"
```
- addedInput schema / properties / breakdowns / items / maxLength
```
Added value: +100
```
- addedInput schema / properties / breakdowns / items / minLength
```
Added value: +1
```
- addedInput schema / properties / breakdowns / items / pattern
```
Added value: +"^[A-Za-z][A-Za-z0-9_]*$"
```
- addedInput schema / properties / breakdowns / items / type
```
Added value: +"string"
```
- removedInput schema / properties / filtering / items / additionalProperties
```
Removed value: -false
```
- removedInput schema / properties / timeRange / additionalProperties
```
Removed value: -false
```
- removedInput schema / properties / timeRange / properties / until / $ref
```
Removed value: -"#/properties/timeRange/properties/since"
```
- addedInput schema / properties / timeRange / properties / until / pattern
```
Added value: +"^\\d{4}-\\d{2}-\\d{2}$"
```
- addedInput schema / properties / timeRange / properties / until / type
```
Added value: +"string"
```
- changedOutput schema / properties / result / anyOf
```
Previous value: -[
-  {
-    "additionalProperties": true,
-    "properties": {},
-    "type": "object"
-  },
-  {
-    "items": {},
-    "type": "array"
-  },
-  {
-    "type": "string"
-  },
-  {
-    "type": "number"
-  },
-  {
-    "type": "boolean"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "properties": {},
+    "type": "object"
+  },
+  {
+    "items": {},
+    "type": "array"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "number"
+  },
+  {
+    "type": "boolean"
+  },
+  {
+    "type": "null"
+  }
+]
```
First observedv2.0.1Sep 23, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive, so the safety profile is covered. The description adds meaningful context beyond that: fields must be validated native names and calculated aliases are rejected, and this tool exists as a forward-compatibility escape hatch. It does not mention rate limits or Meta's async report behavior, keeping it from a 5.

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

Conciseness5/5

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

Two tight sentences, with the core action and scope front-loaded and the sibling differentiation immediately after. No filler or restatement of the title.

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

Completeness4/5

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

With an output schema present and full schema coverage, the description only needs to convey intent and when to reach for it, which it does. It could add a note about compatibility constraints when combining breakdowns or the timeRange vs datePreset choice, but those are mitigated by schema descriptions.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all 14 parameters including enums, patterns, and defaults. The description only echoes the capability list (breakdowns, attribution windows, filters, sort, summary, pagination) without adding syntax or constraint detail beyond the schema, so baseline 3 applies.

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 names a specific verb (Query) and resource (the Meta Insights edge) and enumerates the capabilities it exposes, then explicitly contrasts itself with meta_get_insights as the raw/early-field path. An agent can distinguish it from the curated sibling without opening either schema.

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?

It states the selecting condition clearly: use this when Meta adds fields before the curated metric catalog is updated. The alternative (meta_get_insights) is named, though the inverse guidance ('prefer meta_get_insights for standard curated metrics') is only implied rather than stated.

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

Deploy Server