Guide to Instagram posts data

You can perform Instagram posts searches by calling the Meta Content Library API client get() method, syntax and parameters. It also shows how to perform basic queries using the method with the instagram/posts/preview path. This document describes the parameters and shows you how to perform basic queries by using this method.

Public Instagram accounts include professional accounts for businesses and creators. They also include a subset of personal accounts that have privacy set to public, and have either a verified badge or a threshold number of followers. The threshold number of followers depends on the version of the API:

• Version 6.0 requires 100 or more followers
• Version 5.0 requires 1,000 or more followers

All of the examples in this document are taken from a Secure Research Environment use case and assume you have already created a Python or R Jupyter notebook and have created a client object. See Getting started to learn more.

See Data dictionary for detailed information about the fields that are available on an Instagram post node.

Parameters

Sample Queries

Search for Instagram posts by keyword

To search for all public posts from public Instagram accounts that contain a specific keyword, use get() method with the q parameter. See Advanced search guidelines for information about how multiple keyword searches are handled.

library(reticulate)
client <- import("metacontentlibraryapi")$MetaContentLibraryAPIClient

client$set_default_version(client$LATEST_VERSION)

# Search for posts with specific keyword
response <- client$get(
        path = "instagram/posts/preview", 
        params = list('q' = "cybercrime")
)

# No results are displayed until you provide display instructions:  
jsonlite::fromJSON(response$text, flatten=TRUE) # Display first page

# Fetch next page
if (client$has_next_page(response)) {
    response <- client$query_next_page(response)
    jsonlite::fromJSON(response$text, flatten=TRUE) # Display second page
}

from metacontentlibraryapi import MetaContentLibraryAPIClient as client

client.set_default_version(client.LATEST_VERSION)

# Search for posts with specific keyword
response = client.get(
       path="instagram/posts/preview", 
       params={"q":"cybercrime"}
)

# No results are displayed until you provide display instructions:  
display(response.json()) # First page 

# Fetch next page
if client.has_next_page(response):
    response = client.query_next_page(response)
    display(response.json()) # Display second page

This example would return only 10 results per page. You can use the query_next_page() and has_next_page() to get the next page of 10 results until all the results have been returned. See Search guide for other display and storage options.

The API only returns posts from Instagram accounts that can be returned on their respective paths (instagram/accounts/preview).

Search for posts containing a specific content type

Use the content_types parameter to specify content types you want included in search results.

# Search for Instagram story highlights
response <- client$get(
path="instagram/posts/preview", 
params=list("q"="example", "content_types"="stories")
)

# Search for Instagram story highlights
response = client.get(
    path="instagram/posts/preview",
    params={"q":"example","content_types":["stories"]},
)

Request specific fields

To have the API return only specific fields on any Instagram posts in the response, use the get() method with the fields parameter and a comma-separated list of fields you want included. If omitted, default fields will be returned.

# Create an endpoint including a list of fields:
response <- client$get(
       path = "instagram/posts/preview", 
       params = list('q' = "cybercrime", 'fields'='id,text,creation_time')
)

jsonlite::fromJSON(response$text, flatten=TRUE) # Display first page

# Create an endpoint including a list of fields:
response = client.get(
       path="instagram/posts/preview", 
       params={"q":"cybercrime", "fields": "id,text,creation_time"}
)

display(response.json()) # Display first page

Search for posts by post ID

To search for posts with specific post IDs (that you obtained from a previous post search), use get() method with the post_ids parameter specifying a list of post IDs to include in the results.

# Search for posts with specific post IDs
response <- client$get(
        path = "instagram/posts/preview", 
        params = list('post_ids'=list('7069734086407812'))
)

jsonlite::fromJSON(response$text, flatten=TRUE) # Display first page

# Search for posts with specific post IDs
response = client.get(
        path="instagram/posts/preview", 
        params={"post_ids": ["7069734086407812"]}
)

display(response.json()) # Display first page

Search for posts from specific Instagram accounts

Searching for posts from specific Instagram accounts requires that you first obtain account IDs by using get() method with instagram/accounts/preview path. The search results will include the ID field by default (you don't have to specify it in your query). See Guide to Instagram accounts data to learn about this method.

The IDs that are displayed are Meta Content Library IDs that protect user privacy and will not match the IDs of the content on Meta platforms. These Meta Content Library IDs are the ones you use in your subsequent post searches.

To search for posts from specific accounts, use account_ids parameter, and with or without the q parameter. q is not required but can be added to further filter posts. It does not matter when the posts were created. If you omit the q parameter, all public posts from the specified accounts are returned.

# Search for posts from specific account IDs
response <- client$get(
        path = "instagram/posts/preview",
        params = list('account_ids'='315242517956050')
)

jsonlite::fromJSON(response$text, flatten=TRUE) # Display first page

# Search for posts from specific post IDs
response = client.get(
        path="instagram/posts/preview",
        params={"account_ids": "315242517956050"}
)

display(response.json()) # Display first page

Search for posts containing images with the search term

To search for Instagram posts that include images containing a search term, use the search_scope parameter. You can search for text in images posted on Instagram within approximately the last 180 days. In the following example, the query returns text-only and text-in-image posts:

# Search for instagram posts with images containing query term
response <- client$get(
path="instagram/posts/preview", 
params=list("q"="example", "search_scope"="post_text_and_image_text")
)

# Search for instagram posts with images containing query term
response = client.get(
    path="instagram/posts/preview",
    params={"q":"example","search_scope": "post_text_and_image_text"}
)

Including multimedia in search results

Multimedia in responses to queries on Secure Research Environment include the type of media (photo, video), a Meta Content Library ID, the duration and any user tags. You can get the URL for the media by querying for ”fields”=”multimedia{url}”.

Multimedia is not included in responses to queries in third-party cleanrooms by default. Third-party cleanroom users can get multimedia by querying for ”fields”=”multimedia”. In addition to the type, Meta Content Library ID, duration and user tags, the URL is included in multimedia responses in third-party cleanrooms. Multimedia is available in posts from Facebook Pages, profiles, groups, and events.

• Include the keyword multimedia in your query (fields parameter) on third-party cleanrooms, because multimedia is not included by default.

• Include the keyword multimedia{url} in your query (fields parameter) on Secure Research Environment to obtain the media URL, because the URL is not included by default.

• To display multimedia in Secure Research Environment use display_media().

• The number of calls allowed that include multimedia is controlled by a multimedia query budget specific to the third-party cleanroom environment. See Rate limiting and query budgeting for multimedia for more information. To download multimedia content, use download_multimedia_by_content_ids() with a list of known content IDs. See Guide to ID-based retrieval for information on how to retrieve content IDs.

# Load required libraries
library(reticulate)
meta_content_library_api <- import("metacontentlibraryapi")
utils <- meta_content_library_api$MetaContentLibraryAPIMultimediaUtils
# Provide a comma-separated list of content ids as strings
ids_to_download <- c("553170087752425", "681021651202495")
# Download the multimedia content
utils$download_multimedia_by_content_ids(ids_to_download)
# The file path is displayed when the above command is run
utils$display_media(<FILE_PATH>)

from metacontentlibraryapi import MetaContentLibraryAPIMultimediaUtils as utils
from typing import List
# Provide a comma-separated list of content ids as strings
ids_to_download: List[str] = ['553170087752425', '681021651202495'] # List of IDs to download
# You will receive the path of each content id as output
# You can also view multimedia in media folder with path media/<content_id>/
utils.download_multimedia_by_content_ids(ids_to_download, response=response)
# The file path is displayed when the above command is run
utils.display_media(<FILE_PATH>)

Learn more

• Getting started
• Search guide
• Data dictionary
• Advanced search guidelines
• Guide to Instagram accounts data
• Rate limiting and query budgeting for multimedia