IG Media Insights

Represents social interaction metrics on an IG Media object.

Available for the Instagram API with Facebook Login.

Creating

This operation is not supported.

Reading

GET /<IG_MEDIA_ID>/insights

Get insights data on an IG Media object.

Limitations

• Insights data is not available for any media within an album IG Media.
• Story media metrics are only available for 24 hours, even if the stories are archived or highlighted. To get the latest insights for a story before it expires, set up a Webhook for the Instagram topic and subscribe to the story_insights field.
• Story media metrics with values less than 5 return an error code 10 with the message (#10) Not enough viewers for the media to show insights.
• For Stories created by users in Europe and Japan, the replies metric now returns a value of 0.
• For Stories, replies made by users in Europe and Japan are not included in replies calculations.
• If insights data you are requesting does not exist or is currently unavailable, the API returns an empty data set instead of 0 for individual metrics.
• Data used to calculate metrics can be delayed up to 48 hours.

Requirements

Metrics

Request Syntax

GET https://graph.facebook.com/<API_VERSION>/<IG_MEDIA_ID>/insights
  ?metric=<LIST_OF_METRICS>
  &breakdown=<LIST_OF_BREAKDOWNS>
  &access_token=<ACCESS_TOKEN>

Path Parameters

Query String Parameters

Breakdown

You can also specify one or more breakdowns, and the results will be broken down into smaller sets based on the specified breakdown. Values can be:

• action_type — Only compatible with the profile_activity metric. Break down results by profile UI component that viewers tapped or clicked after viewing the app user's profile. Response values can be:
  • BIO_LINK_CLICKED
  • CALL
  • DIRECTION
  • EMAIL
  • OTHER
  • TEXT
• story_navigation_action_type — Break down results by navigation action taken by the viewer upon viewing the media. Adding all of these action types will give you the total navigation insigts.
  • TAP_BACK equals "Back" on the native interface.
  • TAP_EXIT equals "Exit" on the native interface.
  • TAP_FORWARD equals "Forward" on the native interface.
  • SWIPE_FORWARD equals "Next Story" on the native interface.

Refer to the Metrics table to determine which metrics support breakdowns and which breakdowns they support. If you request a metric that doesn't support breakdowns, the API will return an error ("An unknown error has occurred."), so be careful if requesting multiple metrics in a single query.

Metrics

Reels Metrics

Post Metrics

The following metrics are available on image and Album carousels IG Media published as a Post. IGTV is not supported.

Story Metrics

The following metrics are available on IG Media published as a Story.

Response

A JSON object containing the results of your query. Results can include the following data, based on your query specifications:

{
  "data": [
    {
      "name": "{name}",
      "period": "{period}",
      "values": [
        {
          "value": {value}
        }
      ],
      "title": "{title}",
      "description": "{description}",
      "total_value": {
        "value":{value},
        "breakdowns": [
          {
            "dimension_keys": [
              "{dimension-key-1}",
              "{dimension-key-2}"
              ...
            ],
            "results": [
              {
                "dimension_values": [
                  "dimension-value-1",
                  "dimension-value-2"
                  ...
                ],
                "value": {value}
              },
              ...
            ]
          }
        ]
      },
      "id": "{id}"
    }
  ]
}

Response Contents

Sample Post Metric Request

curl -i -X GET \
 "https://graph.facebook.com/v21.0/17932174733377207/insights?metric=profile_activity&breakdown=action_type&access_token=EAAOc..."

Sample Post Metric Response

{
  "data": [
    {
      "name": "profile_activity",
      "period": "lifetime",
      "values": [
        {
          "value": 4
        }
      ],
      "title": "Profile activity",
      "description": "[IG Insights] This header is the name of a metric that appears on an educational info sheet for a particular post, story, video or promotion. This metric is the sum of all profile actions people take when they engage with this content.",
      "total_value": {
        "value": 4,
        "breakdowns": [
          {
            "dimension_keys": [
              "action_type"
            ],
            "results": [
              {
                "dimension_values": [
                  "email"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "text"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "direction"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "bio_link_clicked"
                ],
                "value": 1
              }
            ]
          }
        ]
      },
      "id": "17932174733377207/insights/profile_activity/lifetime"
    }
  ]
}

Sample Story Metric Request

curl -i -X GET \
 "https://graph.facebook.com/v21.0/17969782069736348/insights?metric=navigation&breakdown=story_navigation_action_type&access_token=EAAOc..."

Sample Story Metric Response

{
  "data": [
    {
      "name": "navigation",
      "period": "lifetime",
      "values": [
        {
          "value": 25
        }
      ],
      "title": "Navigation",
      "description": "This is the total number of actions taken from your story. These are made up of metrics like exited, forward, back and next story.",
      "total_value": {
        "value": 25,
        "breakdowns": [
          {
            "dimension_keys": [
              "story_navigation_action_type"
            ],
            "results": [
              {
                "dimension_values": [
                  "tap_forward"
                ],
                "value": 19
              },
              {
                "dimension_values": [
                  "tap_back"
                ],
                "value": 4
              },
              {
                "dimension_values": [
                  "tap_exit"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "swipe_forward"
                ],
                "value": 1
              }
            ]
          }
        ]
      },
      "id": "17969782069736348/insights/navigation/lifetime"
    }
  ]
}

Updating

This operation is not supported.

Deleting

This operation is not supported.