### cURL Example for Catalog Product Search Source: https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-user/catalog_product_search This cURL command demonstrates how to make a GET request to the catalog product search endpoint, including query parameters for catalog ID, search term, and access token. ```bash curl -i -X GET \ "https://graph.facebook.com/v25.0/90010177253934/catalog_product_search?catalog_id=960179311066902&q=gummy&access_token=EAAOc" ``` -------------------------------- ### Example JSON Response for Media Objects Source: https://developers.facebook.com/docs/instagram-platform/instagram-api-with-facebook-login/get-started This is an example of the JSON response you can expect when successfully querying the `GET /{ig-user-id}/media` endpoint. It includes a list of media object IDs and pagination information. ```json { "data": [ { "id": "17918195224117851" }, { "id": "17895695668004550" }, { "id": "17899305451014820" }, { "id": "17896450804038745" }, { "id": "17881042411086627" }, { "id": "17869102915168123" } ], "paging": { "cursors": { "before": "QVFIUkdGRXA2eHNNTUs4T1ZAXNGFxQTAtd3U4QjBLd1B2NXRMM1NkcnhqRFdBcEUzSDVJZATFoLWtXMWZAGU2VrRTk2RHVtTVlDckI2NjN0UERFa2JrUk4yMW13", "after": "QVFIUmlwbnFsM3N2cV9lZAFdCa0hDeV9qMVliT0VuMmJyNENxZA180c0t6VjFQVEJaTE9XV085aU92OUFLNFB6Szd2amo5aV9rTlVBcnNlWmEtMzYxcE1HSFR3" } } } ``` -------------------------------- ### cURL Example Response for Available Catalogs Source: https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-user/available_catalogs This is an example of a successful response from the cURL request, showing the details of an available product catalog. ```json { "data": [ { "catalog_id": "960179311066902", "catalog_name": "Jay's Favorite Snacks", "shop_name": "Jay's Bespoke", "product_count": 11 } ] } ``` -------------------------------- ### Example Response for Getting Comments Source: https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-media/comments This is an example of the JSON response when retrieving comments for a media object, including timestamp, text, and ID for each comment. ```JSON { "data": [ { "timestamp": "2017-08-31T19:16:02+0000", "text": "This is awesome!", "id": "17870913679156914" }, { "timestamp": "2017-08-31T18:10:30+0000", "text": "*Sniff*", "id": "17873440459141021" } ] } ``` -------------------------------- ### Example Response for Creating a Comment Source: https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-media/comments This is an example of the JSON response received after successfully creating a comment. ```JSON { "id": "17870913679156914" } ``` -------------------------------- ### cURL Request and Response Examples Source: https://developers.facebook.com/docs/instagram-platform/reference/refresh_access_token Example cURL command to refresh an access token and the corresponding JSON response. ```bash curl -X GET \ 'https://graph.instagram.com/refresh_access_token?grant_type=ig_refresh_token&access_token=F4RVB...' ``` ```json { "access_token": "c3oxd...", "token_type": "bearer", "expires_in": 5183944 } ``` -------------------------------- ### Get Creator Insights with Breakdown Source: https://developers.facebook.com/docs/instagram-platform/instagram-api-with-facebook-login/creator-marketplace This example shows how to fetch specific creator insights, such as reach, with a breakdown by follow type. Replace placeholders with actual creator username, desired fields, and your access token. ```curl curl -G \ -d 'username=' \ -d 'fields=insights.metrics(creator_reach).breakdown(follow_type)' \ -d 'access_token=' \ 'https://graph.facebook.com/v25.0//creator_marketplace_creators' ``` -------------------------------- ### Get Story Metric Source: https://developers.facebook.com/docs/instagram-platform/reference/instagram-media/insights This example shows how to retrieve story-related metrics, such as navigation actions, for a specific media object. It includes parameters for specifying the metric and breakdown. ```APIDOC ## Get Story Metric ### Description Retrieves story-specific insights, like navigation actions, for a given media ID. ### Method GET ### Endpoint `https://graph.instagram.com/v25.0/{media-id}/insights?metric={metric_name}&breakdown={breakdown_name}` ### Parameters #### Query Parameters - **metric** (string) - Required - The metric to retrieve (e.g., `navigation`). - **breakdown** (string) - Optional - The breakdown dimension for the metric (e.g., `story_navigation_action_type`). - **access_token** (string) - Required - Your Instagram API access token. ### Request Example ```curl curl -i -X GET \ "https://graph.instagram.com/v25.0/17969782069736348/insights?metric=navigation&breakdown=story_navigation_action_type&access_token=EAAOc..." ``` ### Response #### Success Response (200) - **data** (array) - Contains the metric data. - **name** (string) - The name of the metric. - **period** (string) - The period for which the metric is calculated (e.g., `lifetime`). - **values** (array) - An array of metric values. - **value** (integer) - The metric value. - **title** (string) - The human-readable title of the metric. - **description** (string) - A description of the metric. - **total_value** (object) - Contains the total value and breakdowns. - **value** (integer) - The total metric value. - **breakdowns** (array) - Breakdown details for the metric. - **dimension_keys** (array) - Keys for the dimensions. - **results** (array) - Results for each dimension value. - **dimension_values** (array) - Values of the dimensions. - **value** (integer) - The metric value for this dimension. - **id** (string) - The unique ID for the insight. #### Response Example ```json { "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" } ] } ``` ``` -------------------------------- ### Example Redirect URI Response Source: https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login/business-login This is an example of a successful authorization redirect URI response. Ensure to strip the '#_' appended to the end of the URI. ```http https://my.m.redirect.net/?code=**abcdefghijklmnopqrstuvwxyz**#_ ``` -------------------------------- ### Media Type Not Supported Error Example Source: https://developers.facebook.com/docs/instagram-platform/reference/instagram-media An example of an error response when the media type is not supported for an endpoint. ```APIDOC #### Example response (Failure, Media Type Not Supported) ```json { "error": { "message": "Fatal", "type": "OAuthException", "code": -1, "error_subcode": 2207073, "is_transient": false, "error_user_title": "Media Type Not Supported", "error_user_msg": "The media type is not supported for this endpoint", "fbtrace_id": "Api-OlNdfcpOwIu6hNaT5Kw" } } ``` ``` -------------------------------- ### cURL Example Response for Catalog Product Search Source: https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-user/catalog_product_search This is an example response from a cURL request to search for products. It shows a product matching the search query 'gummy' with its associated details and product variants. ```json { "data": [ { "product_id": 3231775643511089, "merchant_id": 90010177253934, "product_name": "Gummy Wombats", "image_url": "https://scont...", "retailer_id": "oh59p9vzei", "review_status": "approved", "is_checkout_flow": true, "product_variants": [ { "product_id": 5209223099160494 }, { "product_id": 7478222675582505, "variant_name": "Green Gummy Wombats" } ] } ] } ``` -------------------------------- ### Developer Setup and App Creation Source: https://developers.facebook.com/docs/instagram-platform/overview Steps to register as a Meta developer and create an app, including required products based on login type. ```APIDOC ## Develop with Meta ### Description Before you can integrate a Meta Technologies API into your app, you must register as a Meta developer and then create an app in the Meta App Dashboard that represents your app. When creating an app, you will add the following products depending on login type: | Business Login for Instagram | Facebook Login for Business | |---|---| | **Products Required** | | * **Instagram** > Instagram API setup with Instagram login | | * **Facebook Login for Business** * **Messenger** , including Instagram settings for sending and receiving messages * **Instagram** > Instagram API setup with Facebook login ### App IDs App IDs are required during authentication and can be found in the app's Meta App Dashboard. Apps that use Facebook Login for Business will use the Meta app ID displayed at the top of the Meta App Dashboard for your app. Apps that use Business Login for Instagram will use the Instagram app ID displayed on the **Instagram > API setup with Instagram login** section of the dashboard. ``` -------------------------------- ### Instagram OAuth Authorize HTTP Example Source: https://developers.facebook.com/docs/instagram-platform/reference/oauth-authorize An example of a complete HTTP GET request to the Instagram OAuth authorize endpoint. Replace placeholders with your actual app credentials and desired scopes. ```http https://api.instagram.com/oauth/authorize ?client_id=990602627938098 &redirect_uri=https://socialsizzle.herokuapp.com/auth/ &scope=instagram_business_basic &response_type=code ``` -------------------------------- ### Search for Products by Name or SKU Source: https://developers.facebook.com/docs/instagram-platform/instagram-api-with-facebook-login/product-tagging This example demonstrates how to search for specific products within a catalog using a query string for the product name or SKU. If no query is provided, all tag-eligible products are returned. ```bash curl -i -X GET \ "https://graph.facebook.com/v25.0/90010177253934/catalog_product_search?catalog_id=960179311066902&q=gummy&access_token=EAAOc..." ``` -------------------------------- ### Sample Response for Media Container Creation Source: https://developers.facebook.com/docs/instagram-platform/content-publishing/resumable-uploads On successful initialization, the API returns a JSON object containing the media container ID and Meta URI, which are necessary for subsequent upload steps. ```json { "id": "", "uri": "https://rupload.facebook.com/ig-api-upload//" } ``` -------------------------------- ### Get Media Insights with Breakdown Source: https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-media/insights This example shows how to retrieve media insights and break down the `profile_activity` metric by `action_type`. ```APIDOC ## GET /INSTAGRAM_BUSINESS_ACCOUNT_ID/insights ### Description Retrieves insights for a specified Instagram media object. You can include the `breakdown` parameter to divide data into smaller sets based on the specified breakdown value. ### Method GET ### Endpoint `/{instagram-business-account-id}/insights` ### Parameters #### Query Parameters - **metric** (string) - Required - The metric(s) you want to retrieve. Example: `profile_activity`, `navigation`. - **breakdown** (string) - Optional - Divides data into smaller sets. Compatible values include `action_type` (for `profile_activity`) and `story_navigation_action_type` (for `navigation`). - **access_token** (string) - Required - Your valid API access token. ### Request Example ```APIDOC GET https://graph.facebook.com/v25.0/17932174733377207/insights?metric=profile_activity&breakdown=action_type&access_token=EAAOc... ``` ### Response #### Success Response (200) Returns a JSON object containing the requested insights data. The structure includes `data`, `name`, `period`, `values`, `title`, `description`, `id`, and `total_value` which can contain `breakdowns` if requested. ```json { "data": [ { "name": "profile_activity", "period": "lifetime", "values": [ { "value": 150 } ], "title": "Profile Activity", "description": "Profile Activity", "total_value": { "value": 150, "breakdowns": [ { "dimension_keys": [ "action_type" ], "results": [ { "dimension_values": [ "BIO_LINK_CLICKED" ], "value": 50 }, { "dimension_values": [ "CALL" ], "value": 30 }, { "dimension_values": [ "DIRECTION" ], "value": 20 }, { "dimension_values": [ "EMAIL" ], "value": 10 }, { "dimension_values": [ "OTHER" ], "value": 20 }, { "dimension_values": [ "TEXT" ], "value": 20 } ] } ] }, "id": "17932174733377207" } ] } ``` ``` -------------------------------- ### Example Redirect URL Source: https://developers.facebook.com/docs/instagram-platform/instagram-api-with-facebook-login/business-login-for-instagram This URL demonstrates the format of a redirect after a successful authentication, containing various token fragments. ```url https://my-clever-redirect-url.com/success/?#access_token=EAAHm...&data_access_expiration_time=1658889585&expires_in=4815&long_lived_token=ABAEs... ``` -------------------------------- ### Get Demographic Metrics Source: https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-user/insights This example demonstrates how to retrieve demographic insights, such as engaged audience demographics by country, for an Instagram user. ```APIDOC ## GET /insights ### Description Retrieves demographic metrics for an Instagram user. ### Method GET ### Endpoint `/{ig-user-id}/insights` ### Query Parameters - **metric** (string) - Required - The insight metric to retrieve (e.g., `engaged_audience_demographics`). - **period** (string) - Required - The period for which to retrieve insights (e.g., `lifetime`). - **timeframe** (string) - Required - The timeframe for the insights (e.g., `last_90_days`). - **breakdowns** (string) - Optional - Specifies how to break down the metric (e.g., `country`). - **metric_type** (string) - Optional - Specifies the type of metric value to return (e.g., `total_value`). - **access_token** (string) - Required - Your app's access token. ### Request Example ```bash curl -i -X GET \ "https://graph.facebook.com/v25.0/17841405822304914/insights?metric=engaged_audience_demographics&period=lifetime&timeframe=last_90_days&breakdowns=country&metric_type=total_value&access_token=EAAOc..." ``` ### Response #### Success Response (200) - **data** (Array) - An array of objects describing your results. - **name** (String) - Metric requested. - **period** (String) - Period requested. - **title** (String) - Metric title. - **description** (String) - Metric description. - **id** (String) - A string describing the query's path parameters. - **paging** (Object) - An object containing URLs used to request the next set of results. - **previous** (String) - URL to retrieve the previous page of results. - **next** (String) - URL to retrieve the next page of results. #### Response Example (Response structure will vary based on the specific metric and breakdowns requested. Refer to the general response structure for insights.) ``` -------------------------------- ### Example Request to Get IG Container Status Source: https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-container This cURL command demonstrates how to request the status code and ID of an IG Container. ```bash curl -X GET \ 'https://graph.instagram.com/17889615691921648?fields=status_code&access_token=IGQVJ...' ``` -------------------------------- ### Sample Verification Request Source: https://developers.facebook.com/docs/instagram-platform/instagram-api-with-facebook-login/webhooks This is an example of a GET request sent by Instagram to verify your webhook endpoint. It includes hub.mode, hub.challenge, and hub.verify_token parameters. ```http GET https://www.your-clever-domain-name.com/webhooks? hub.mode=subscribe& hub.challenge=1158201444& hub.verify_token=meatyhamhock ``` -------------------------------- ### Sample Response for Getting Page's IG User Source: https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/page Example JSON response when successfully retrieving the IG User connected to a Facebook Page. ```JSON { "instagram_business_account": { "id": "17841405822304914" }, "id": "134895793791914" } ``` -------------------------------- ### Sample Media Publish Request Source: https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-user/media_publish Example of a POST request to publish a specific IG container. ```http POST graph.facebook.com /17841405822304914/media_publish ?creation_id=17889455560051444 ``` -------------------------------- ### Sample Request to Read IG Hashtag Source: https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-hashtag Example of a GET request to retrieve the ID and name of an IG Hashtag. Replace placeholders with your actual values. ```curl GET https://graph.facebook.com/17841593698074073 ?fields=id,name &access_token=EAADd... ``` -------------------------------- ### Example Live Media Response Data Source: https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-user/live_media This is an example of the data returned for a live media object, including its ID, type, owner, username, and associated comments. Note that the `comments` field may contain an array of comment objects. ```json { "id":"90010498116233", "media_type":"BROADCAST", "media_product_type":"LIVE", "owner":{ "id":"17841405822304914" }, "username":"jayposiris", "comments":{ "data":[ { "hidden": false, "id": "17907364514064687", "like_count": 0, "media": { "id": "17892642502701087" }, "text": "@jayposiris", "timestamp": "2021-08-17T21:23:07+0000", "username": "bztest0316_11", "from": { "id": "5895605157123796", "username": "bztest0316_11" } } ] } } ``` -------------------------------- ### Get Post Metric Source: https://developers.facebook.com/docs/instagram-platform/reference/instagram-media/insights This example demonstrates how to retrieve insights for a specific Instagram post, such as profile activity. It outlines the structure of the response, including metric names, values, and breakdowns. ```APIDOC ## Get Post Metric ### Description Retrieves insights for a specific Instagram post, detailing metrics like profile activity and engagement. ### Method GET ### Endpoint `https://graph.instagram.com/v25.0/{media-id}/insights?metric={metric_name}` ### Parameters #### Query Parameters - **metric** (string) - Required - The metric to retrieve (e.g., `profile_activity`). - **access_token** (string) - Required - Your Instagram API access token. ### Response #### Success Response (200) - **data** (array) - Contains the metric data. - **name** (string) - The name of the metric. - **period** (string) - The period for which the metric is calculated (e.g., `lifetime`). - **values** (array) - An array of metric values. - **value** (integer) - The metric value. - **title** (string) - The human-readable title of the metric. - **description** (string) - A description of the metric. - **total_value** (object) - Contains the total value and breakdowns. - **value** (integer) - The total metric value. - **breakdowns** (array) - Breakdown details for the metric. - **dimension_keys** (array) - Keys for the dimensions. - **results** (array) - Results for each dimension value. - **dimension_values** (array) - Values of the dimensions. - **value** (integer) - The metric value for this dimension. - **id** (string) - The unique ID for the insight. #### Response Example ```json { "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" } ] } ``` ``` -------------------------------- ### cURL Example for Creating Product Tags Source: https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-media/product_tags This cURL command demonstrates how to send a POST request to create or update product tags on an IG Media. It includes the necessary parameters like updated_tags and access_token. ```bash curl -i -X POST \ "https://graph.facebook.com/v25.0/90010778325754/product_tags?updated_tags=%5B%0A%20%20%7B%0A%20%20%20%20product_id%3A'3859448974125379'%2C%0A%20%20%20%20x%3A%200.5%2C%0A%20%20%20%20y%3A%200.8%0A%20%20%7D%0A%5D&access_token=EAAOc..." ``` ```json { "success": true } ``` -------------------------------- ### Get Interaction Metrics Source: https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-user/insights This example shows how to retrieve interaction metrics such as reach for a specific Instagram user. It specifies the metric, period, breakdown, metric type, and a time range. ```APIDOC ## GET /insights ### Description Retrieves interaction metrics for an Instagram user. ### Method GET ### Endpoint `/{ig-user-id}/insights` ### Query Parameters - **metric** (string) - Required - The insight metric to retrieve (e.g., `reach`, `impressions`). - **period** (string) - Required - The period for which to retrieve insights (e.g., `day`, `week`, `month`, `lifetime`). - **breakdowns** (string) - Optional - Specifies how to break down the metric (e.g., `media_product_type`, `country`). - **metric_type** (string) - Optional - Specifies the type of metric value to return (e.g., `total_value`). - **since** (integer) - Optional - Unix timestamp for the start of the period. - **access_token** (string) - Required - Your app's access token. ### Request Example ```bash curl -i -X GET \ "https://graph.facebook.com/v25.0/17841405822304914/insights?metric=reach&period=day&breakdown=media_product_type&metric_type=total_value&since=1658991600&access_token=EAAOc..." ``` ### Response #### Success Response (200) - **data** (Array) - An array of objects describing your results. - **name** (String) - Metric requested. - **period** (String) - Period requested. - **title** (String) - Metric title. - **description** (String) - Metric description. - **total_value** (Object) - Object describing requested breakdown values. - **value** (Integer) - Sum of requested metric values. - **breakdowns** (Array) - An array of objects describing the breakdowns requested and their results. - **dimension_keys** (Array) - An array of strings describing breakdowns requested in the query. - **results** (Array) - An array of objects describing each breakdown set. - **dimension_values** (Array) - An array of strings describing breakdown set values. - **value** (Integer) - Sum of breakdown set values. - **id** (String) - A string describing the query's path parameters. - **paging** (Object) - An object containing URLs used to request the next set of results. - **previous** (String) - URL to retrieve the previous page of results. - **next** (String) - URL to retrieve the next page of results. #### Response Example ```json { "data": [ { "name": "reach", "period": "day", "title": "Accounts reached", "description": "The number of unique accounts that have seen your content, at least once, including in ads. Content includes posts, stories, reels, videos and live videos. Reach is different from impressions, which may include multiple views of your content by the same accounts. This metric is estimated and in development.", "total_value": { "value": 224, "breakdowns": [ { "dimension_keys": [ "media_product_type" ], "results": [ { "dimension_values": [ "CAROUSEL_CONTAINER" ], "value": 100 }, { "dimension_values": [ "POST" ], "value": 124 } ] } ] }, "id": "17841405309211844/insights/reach/day" } ], "paging": { "previous": "https://graph.face...", "next": "https://graph.face..." } } ``` ``` -------------------------------- ### Initialize Resumable Upload Source: https://developers.facebook.com/docs/instagram-platform/content-publishing/resumable-uploads Initializes a resumable upload session and creates a media container for the video on Meta servers. ```APIDOC ## POST //media?upload_type=resumable ### Description Initializes the upload and creates a media container for the video. ### Method POST ### Endpoint https://graph.facebook.com//media?upload_type=resumable ### Parameters #### Query Parameters - **access_token** (string) - Required - Set to your app user's access token - **upload_type** (string) - Required - Set to `resumable` - **media_type** (string) - Required - Set to `REELS`, `STORIES`, or `VIDEO` - **is_carousel_item** (boolean) - Required - Set to `true` for videos in carousels #### Request Body (No explicit request body documented, parameters are typically sent as query parameters or form data in the example) ### Request Example ```curl https://graph.facebook.com///media -H "Content-Type: application/json" -H "Authorization: Bearer " -d '{ "media_type": "" "upload_type=resumable" }' ``` ### Response #### Success Response (200) - **id** (string) - The ID for the media container. - **uri** (string) - The Meta URI for uploading the video. #### Response Example ```json { "id": "", "uri": "https://rupload.facebook.com//" } ``` ``` -------------------------------- ### cURL Example for Token Exchange Source: https://developers.facebook.com/docs/instagram-platform/reference/access_token This cURL command demonstrates how to make the request to exchange a short-lived access token for a long-lived one. Replace placeholders with your actual credentials. ```bash curl -X GET "https://graph.instagram.com/access_token?grant_type=ig_exchange_token&&client_secret=eb87G...&access_token=IGQVJ..." ``` -------------------------------- ### cURL Example for Reading an IG Comment Source: https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-comment This cURL command demonstrates how to make a GET request to retrieve specific fields of an IG Comment. Replace placeholders with your actual values. ```bash curl -i -X GET \ "https://graph.instagram.com/v25.0/17881770991003328?fields=hidden%2Cmedia%2Ctimestamp&access_token=EAAOc..." ``` -------------------------------- ### Retrieve all Upcoming Events Source: https://developers.facebook.com/docs/instagram-platform/instagram-api-with-facebook-login/upcoming-events Send a GET request to the //upcoming_events endpoint to retrieve a list of all upcoming events. The response includes the event ID, title, and start time. ```APIDOC ## Retrieve all Upcoming Events ### Description Retrieves a list of all upcoming events for a specified Instagram User ID. ### Method GET ### Endpoint `//upcoming_events` ### Parameters #### Query Parameters - **access_token** (string) - Required - The access token for authentication. ### Request Example ```bash curl -X GET "https://graph.facebook.com/v25.0//upcoming_events?access_token=" ``` ### Response #### Success Response (200) Returns a JSON object containing a list of upcoming events. Each event object includes: - **id** (string) - The unique identifier for the event. - **title** (string) - The title of the event. - **start_time** (string) - The start time of the event in ISO 8601 format. #### Response Example ```json { "data": [ { "id": "", "title":"", "start_time":"2024-04-11T16:00:00+0000" }, { "id": "", "title":"", "start_time":"2024-04-18T16:00:00+0000" }, { "id": "", "title":"", "start_time":"2024-04-25T16:00:00+0000" } ] } ``` ``` -------------------------------- ### Create Tagged Media Container - API Endpoint Source: https://developers.facebook.com/docs/instagram-platform/instagram-api-with-facebook-login/product-tagging Use this endpoint to create a media container for an image or video, specifying product tags. This is a prerequisite for publishing media with product tags. ```bash POST /{ig-user-id}/media ``` -------------------------------- ### Fetch Interaction Metrics Source: https://developers.facebook.com/docs/instagram-platform/api-reference/instagram-user/insights Retrieve interaction metrics such as reach for a given Instagram user profile. This example shows how to get daily reach data broken down by media product type. ```APIDOC ## GET /insights ### Description Retrieve interaction metrics for an Instagram user profile. ### Method GET ### Endpoint `/{user-id}/insights` ### Query Parameters - **metric** (string) - Required - The metric to retrieve (e.g., `reach`, `impressions`). - **period** (string) - Required - The period for the metric (e.g., `day`, `week`, `month`, `lifetime`). - **breakdowns** (string) - Optional - Breakdown dimension (e.g., `media_product_type`, `country`). - **metric_type** (string) - Optional - Type of metric aggregation (e.g., `total_value`). - **since** (integer) - Optional - Unix timestamp for the start date. - **access_token** (string) - Required - Your access token. ### Request Example ```bash curl -i -X GET \ "https://graph.facebook.com/v25.0/17841405822304914/insights?metric=reach&period=day&breakdown=media_product_type&metric_type=total_value&since=1658991600&access_token=EAAOc..." ``` ### Response #### Success Response (200) - **data** (Array) - An array of objects describing your results. - **name** (String) - Metric requested. - **period** (String) - Period requested. - **title** (String) - Metric title. - **description** (String) - Metric description. - **total_value** (Object) - Object describing requested breakdown values. - **value** (Integer) - Sum of requested metric values. - **breakdowns** (Array) - An array of objects describing the breakdowns requested and their results. - **dimension_keys** (Array) - An array of strings describing breakdowns requested in the query. - **results** (Array) - An array of objects describing each breakdown set. - **dimension_values** (Array) - An array of strings describing breakdown set values. - **value** (Integer) - Sum of breakdown set values. - **id** (String) - A string describing the query's path parameters. - **paging** (Object) - An object containing URLs used to request the next set of results. - **previous** (String) - URL to retrieve the previous page of results. - **next** (String) - URL to retrieve the next page of results. #### Response Example ```json { "data": [ { "name": "reach", "period": "day", "title": "Accounts reached", "description": "The number of unique accounts that have seen your content, at least once, including in ads. Content includes posts, stories, reels, videos and live videos. Reach is different from impressions, which may include multiple views of your content by the same accounts. This metric is estimated and in development.", "total_value": { "value": 224, "breakdowns": [ { "dimension_keys": [ "media_product_type" ], "results": [ { "dimension_values": [ "CAROUSEL_CONTAINER" ], "value": 100 }, { "dimension_values": [ "POST" ], "value": 124 } ] } ] }, "id": "17841405309211844/insights/reach/day" } ], "paging": { "previous": "https://graph.face...", "next": "https://graph.face..." } } ``` ``` -------------------------------- ### cURL Example for Reading Live Media Source: https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-user/live_media This cURL command demonstrates how to fetch live media details, including ID, media type, owner, username, and comments, for a specific IG User. It utilizes the `fields` parameter to specify the desired data. ```bash curl -X GET \ 'https://graph.facebook.com/v25.0/17841405822304914/live_media?fields=id,media_type,media_product_type,owner,username,comments&access_token=IGQVJ...' ``` -------------------------------- ### Get User Accounts cURL Example Source: https://developers.facebook.com/docs/instagram-platform/instagram-api-with-facebook-login/business-login-for-instagram Use this cURL command to request a list of Facebook Pages associated with the user, including their access tokens and connected Instagram Business accounts. ```curl curl -i -X GET \ "https://graph.facebook.com/v25.0/me/accounts?fields=id%2Cname%2Caccess_token%2Cinstagram_business_account&access_token=EAACw..." ``` -------------------------------- ### Upload Public Hosted Video for Resumable Session Source: https://developers.facebook.com/docs/instagram-platform/content-publishing Initiate a resumable upload session for a video hosted on a public server. Provide the container ID, access token, and the public URL of the video file. ```bash curl -X POST "https://rupload.facebook.com/ig-api-upload//`" \ -H "Authorization: OAuth " \ -H "file_url: https://example_hosted_video.com" ``` -------------------------------- ### Fetch Demographic Metrics Source: https://developers.facebook.com/docs/instagram-platform/api-reference/instagram-user/insights Retrieve demographic metrics for an Instagram user profile, such as engaged audience demographics. This example shows how to get lifetime demographic data for the last 90 days, broken down by country. ```APIDOC ## GET /insights ### Description Retrieve demographic metrics for an Instagram user profile. ### Method GET ### Endpoint `/{user-id}/insights` ### Query Parameters - **metric** (string) - Required - The metric to retrieve (e.g., `engaged_audience_demographics`). - **period** (string) - Required - The period for the metric (e.g., `lifetime`). - **timeframe** (string) - Optional - The timeframe for the metric (e.g., `last_90_days`). - **breakdowns** (string) - Optional - Breakdown dimension (e.g., `country`). - **metric_type** (string) - Optional - Type of metric aggregation (e.g., `total_value`). - **access_token** (string) - Required - Your access token. ### Request Example ```bash curl -i -X GET \ "https://graph.facebook.com/v25.0/17841405822304914/insights?metric=engaged_audience_demographics&period=lifetime&timeframe=last_90_days&breakdowns=country&metric_type=total_value&access_token=EAAOc..." ``` ### Response #### Success Response (200) - **data** (Array) - An array of objects describing your results. - **name** (String) - Metric requested. - **period** (String) - Period requested. - **title** (String) - Metric title. - **description** (String) - Metric description. - **id** (String) - A string describing the query's path parameters. - **paging** (Object) - An object containing URLs used to request the next set of results. - **previous** (String) - URL to retrieve the previous page of results. - **next** (String) - URL to retrieve the next page of results. #### Response Example (Response structure will be similar to the Interaction Metrics example, with specific demographic data) ``` -------------------------------- ### Welcome Message Flows Response Structure Source: https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login/welcome-message-ads Example JSON response containing a list of welcome message flow objects. ```json [ { "id":"", "name":"", "welcome_message":"", "eligible_platforms": ["instagram"], "last_update_time":"2023-09-01T05:20:38+0000", "is_used_in_ad": false // indicates whether or not a flow is used in an ad }, { "id":"", "name":"", "welcome_message":"", "eligible_platforms": ["instagram"], "last_update_time":"2023-08-25T08:21:48+0000", "is_used_in_ad": true }, { "id":"", "name":"", "welcome_message":"", "eligible_platforms": ["instagram"], "last_update_time":"2023-08-20T07:43:00+0000", "is_used_in_ad": true } ... ... ... ] ``` -------------------------------- ### Sample Audio Search Response Source: https://developers.facebook.com/docs/instagram-platform/content-publishing/audio-api This is an example of the JSON response when searching for audio assets. It includes details such as audio ID, title, artist, duration, and a download URL for previewing the audio. ```json { "audio": [ { "audio_id": "587784541076604", "cover_artwork_thumbnail_uri": "https://scontent-...", "display_artist": "Shuba", "duration_in_ms": 153760, "audio_type": "music", "title": "Birthday Wish", "download_url": "https://scontent-lga3..." } ] } ``` -------------------------------- ### Get IG User Content Publishing Limit Source: https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-user/content_publishing_limit Use this endpoint to retrieve the number of times an IG User has published an IG Container within a specified time period. Include fields like `quota_usage` and `rate_limit_settings` for detailed information. A `since` Unix timestamp can be provided to specify the start of the period, otherwise, it defaults to the last 24 hours. ```curl curl -X GET \ 'https://graph.facebook.com/v25.0/17841405822304914/content_publishing_limit?fields=quota_usage,rate_limit_settings&since=1609969714&access_token=IGQVJ...' ``` -------------------------------- ### Create a Tagged Media Container (Image) Source: https://developers.facebook.com/docs/instagram-platform/instagram-api-with-facebook-login/product-tagging Use the IG User Media endpoint to create a media container with product tags for an image. Ensure the image URL is publicly accessible. The product_tags parameter accepts an array of objects, each with a product_id, x, and y coordinate. ```curl curl -i -X POST \ "https://graph.facebook.com/v25.0/90010177253934/media?image_url=https%3A%2F%2Fupl...&location_id=7640348500&product_tags=%5B%0A%20%20%7B%0A%20%20%20%20product_id%3A'3231775643511089'%2C%0A%20%20%20%20x%3A%200.5%2C%0A%20%20%20%20y%3A%200.8%0A%20%20%7D%0A%5D&access_token=EAAOc..." ``` ```plaintext https://graph.facebook.com/v12.0/90010177253934/media?image_url=https://upl...&location_id=7640348500 &product_tags=[ { product_id:'3231775643511089', x: 0.5, y: 0.8 } ]&access_token=EAAOc... ``` -------------------------------- ### Create Media Container with Partnership Ads Label Source: https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login/content-publishing Creates a media container and adds a partnership ads label. Supports tagging sponsors and enabling the 'Paid partnership' label. ```APIDOC ## Create Media Container with Partnership Ads Label ### Description Creates a media container and applies partnership ads labeling. ### Method POST ### Endpoint `//media` ### Parameters #### Request Body - **image_url** or **video_url** (string) - Required - URL of the media. - **caption** (string) - Required - Caption for the post. - **branded_content_sponsor_ids** (array of integers) - Optional - Instagram user IDs of brands to tag. Maximum 2. - **is_paid_partnership** (boolean) - Optional - Enables the "Paid partnership" label. Automatically true if `branded_content_sponsor_ids` is provided. ### Limitations - Access token requires `instagram_branded_content_creator` or `instagram_basic` permission. - Sponsor accounts must be professional accounts. - Maximum 2 sponsor tags per post. - Not supported on close-friends-only posts or remixed media. ### Request Example ```curl curl -X POST "https://graph.facebook.com///media" \ -H "Authorization: Bearer " \ -d "image_url=" \ -d "caption=" \ -d "branded_content_sponsor_ids=[, ]" \ -d "is_paid_partnership=true" ``` ``` -------------------------------- ### POST /me/welcome_message_flows Source: https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login/welcome-message-ads Update an existing welcome message flow. Flows connected to an advertisement cannot be updated. ```APIDOC ## POST /me/welcome_message_flows ### Description Update an existing flow. Note that flows currently connected to an advertisement cannot be updated. ### Method POST ### Endpoint /me/welcome_message_flows ### Parameters #### Query Parameters - **access_token** (string) - Required - The Instagram user access token. - **flow_id** (string) - Required - The ID of the flow to update. - **name** (string) - Optional - New name for the flow. - **welcome_message** (object) - Optional - New welcome message content. - **platforms** (array) - Optional - New platforms configuration. ### Response #### Success Response (200) - **success** (boolean) - Returns true if the update was successful. ``` -------------------------------- ### Get comments on Instagram media Source: https://developers.facebook.com/docs/instagram-platform/comment-moderation Retrieve all comments for a specific media object using a GET request. ```bash curl -X GET "https:///v25.0//comments" ```