Metrics

Get metrics as tables and grids via API

With component datatable_v1 in POST /metrics/get-data, the metric comes back as tabular data, with columns (metrics) and a breakdown by dimension. There is also datagrid_v1 for grids, such as Instagram stories. One API for every connected account, with no network-by-network integration.

The request

POST /api/metrics/get-data
Authorization: Bearer <merchant token>
x-customer-token: <customer token>

{
  "customer_integration": "<connection uuid>",
  "start": "2026-08-01",
  "end": "2026-08-31",
  "metrics": [
    {
      "id": "80e06171-759e-472e-9cff-25ae8e91e1e0",
      "reference_key": "fb_ads:insights_by_campaign",
      "component": "datatable_v1",
      "metrics": [
        "results",
        "cost_per_results",
        "spend",
        "reach",
        "impressions",
        "ctr",
        "cpc",
        "cpm",
        "frequency"
      ]
    }
  ]
}

What you can do

  • List Meta Ads campaigns with results, cost per result, spend, reach, impressions, CTR, CPC, CPM and frequency using fb_ads:insights_by_campaign.
  • Pick the columns in metrics and the breakdown in dimensions, using the values from the GET /metrics/{integration_slug} catalog.
  • Request tables next to numbers and charts in the same call.
  • Use datagrid_v1 for grids, such as Instagram stories.

Rules and limits

  • Copy the catalog item into metrics[] and swap metrics and dimensions for keys from the catalog's meta.setup if you want a different cut.
  • Catalog items already carry metrics and dimensions in the accepted shape: copy them as they come.
  • The result comes in data, under each metric's id (UUID), in the component's format.
  • If one metric fails on its own, it comes back as an error object and the others come with status 200.
  • Each call reads one connection (customer_integration) and needs the customer's x-customer-token.

Main fields

FieldTypeRequiredDescription
customer_integrationstringYesUUID of the customer's connection the metrics are read from. One per call.
startstringYesStart of the period (YYYY-MM-DD). Must be less than or equal to end.
endstringYesEnd of the period (YYYY-MM-DD).
metrics.reference_keystringYesA catalog metric whose component is datatable_v1 or datagrid_v1, such as fb_ads:insights_by_campaign.
metrics.componentstringYesdatatable_v1 for tabular data; datagrid_v1 for grids, such as Instagram stories.
metrics.metricsarrayYesThe requested columns (for example spend, reach, ctr).
metrics.dimensionsarrayNoThe breakdown of the result. Copy it from the catalog item.

Who it is for

  • Campaign table in your product

    List the customer's campaigns with spend, reach and CTR inside your interface, without integrating Meta Ads.

  • Paid media performance reports

    Build each client's campaign ranking for the agency's monthly report.

  • Agents that analyze campaigns

    An agent reads the table and points out the campaigns with the worst cost per result.

Frequently asked questions

What is the difference between datatable_v1 and datagrid_v1?

datatable_v1 delivers tabular data; datagrid_v1 delivers a grid, such as the Instagram stories one. Each platform's catalog shows which component each metric uses.

How do I break the result down by campaign?

Use fb_ads:insights_by_campaign, the Meta Ads catalog item that already comes with the campaign dimension, and copy its metrics and dimensions.

Can I paginate the table?

The spec does not describe pagination or sorting for tables, so it is not documented here. You shape the result with the period, the metrics and the dimensions.

Related

See everything you can do with Metrics

See Connect applied to your product.

Try it for 15 days with no card, or walk our team through your use case.