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 search/instagram_posts 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 5.0 requires 1,000 or more followers
• Versions 3.0 and 4.0 require 25,000 or more followers

All of the examples in this document are taken from a Researcher Platform 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 = "search/instagram_posts", 
        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="search/instagram_posts", 
       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 (search/instagram_accounts).

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="search/instagram_posts", 
params=list("q"="example", "content_types"="stories")
)

# Search for Instagram story highlights
response = client.get(
    path="search/instagram_posts",
    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 = "search/instagram_posts", 
       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="search/instagram_posts", 
       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 = "search/instagram_posts", 
        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="search/instagram_posts", 
        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 search/instagram_accounts 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 = "search/instagram_posts",
        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="search/instagram_posts",
        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. 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="search/instagram_posts", 
params=list("q"="example", "search_scope"="post_text_and_image_text")
)

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

Including multimedia in search results: Third-party cleanroom environments only

If you are using the Meta Content Library API in an approved third-party cleanroom environment (as opposed to Meta's Researcher Platform), and if that environment supports it, you have the option of including multimedia (photo, video) in your search results. Multimedia in posts from Instagram business, creator, and personal accounts are all eligible.

• Include the keyword multimedia in your query (fields parameter).

• For any media contained in a post, the response will include the type of media (photo, video), an ID, and either the media itself or a link to where the cleanroom environment has stored the media. Whether the media can be displayed directly in the response or not depends on the third-party cleanroom interface.

• 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.

Learn more

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