Guide to Facebook posts data

You can perform Facebook post searches by calling the Meta Content Library API client get() method with the search/facebook_posts path. This document describes the parameters, and shows how to perform basic queries using the method.

All of the examples in this document are taken from a Researcher Platform use case and assume you have created a Jupyter notebook and a client object. See Getting started to learn more.

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

Parameters

Sample queries

Search for posts by keyword

To search for all public posts on Facebook Pages, groups, profiles, and events that contain specific keywords, use 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)

response <- client$get(
        path="search/facebook_posts",
        params = list("q"="cybercrime")
)
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)

response = client.get(
    path="search/facebook_posts",
    params={"q": "cybercrime"}
)
display(response.json()) # Display 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 shows how to iterate through responses by using the query_next_page() method. You can keep calling query_next_page() to get the next page of 10 results, until all the search results have been returned or the limit of 1,000 for synchronous search has been reached. You can call has_next_page() to check if there is more data. See Search guide for other display and storage options.

The API only returns posts made to Facebook Pages, profiles, groups, or events that can be returned on their respective paths (search/facebook_pages, search/facebook_profiles, search/facebook_groups and search/facebook_events).

Search for posts containing specific content types

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

# Search for Facebook story highlights
response <- client$get(
path="search/facebook_posts", 
params=list("q"="example", "content_types"="stories")
)

# Search for Facebook story highlights
response = client.get(
    path="search/facebook_posts",
    params={"q":"example","content_types":["stories"]},
)

Search for posts by post ID

To search for posts with specific post IDs (that you obtained from a previous post search), use 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/facebook_posts",
        params = list("post_ids"=list("877107953929200"))
)

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

Search for posts made to specific Facebook Pages, profiles, groups, or events

Searching for posts made to specific Facebook Pages, profiles, groups, or events requires that you first obtain Page, group, or event IDs by searching using the search/facebook_pages, search/facebook_profiles, search/facebook_groups and search/facebook_events paths. The search results will include the ID field by default (you don't have to specify it in your query). See Guides to learn about these methods.

The IDs that are displayed in the search results 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 posts made to specific Pages, profiles, groups, or events, use the surface_ids parameter with the page_ids, profile_ids, group_ids, or event_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 on the specified Pages, profiles, groups, or events are returned.

# Search for posts made to specific Page IDs
response <- client$get(
        path="search/facebook_posts",
        params = list("surface_ids"=list("282820031228465"))
)

# Search for posts made to specific Page IDs
response = client.get(
        path="search/facebook_posts",
        params={"surface_ids": ["282820031228465"]}
)

# Search for posts made to specific group IDs        
response <- client$get(
        path="search/facebook_posts",
        params = list("surface_ids"=list("339983685122355"))
)

# Search for posts made to specific group IDs   
response = client.get(
        path="search/facebook_posts",
        params={"surface_ids": ["339983685122355"]}
)

# Search for posts made to specific Profile IDs 
response <- client$get(
        path="search/facebook_posts",
        params = list("surface_ids"=list("755732639815385"))
)

# Search for posts made to specific Profile IDs 
response = client.get(
        path="search/facebook_posts",
        params={"surface_ids": ["755732639815385"]}
)

# Search for posts made to specific event IDs 
response <- client$get(
        path="search/facebook_posts",
        params = list("surface_ids"=list("1025592588867344"))
)

# Search for posts made to specific event IDs
response = client.get(
        path="search/facebook_posts",
        params={"surface_ids": ["1025592588867344"]}
)

# Search for posts made to specific Page IDs and specific group IDs  
response <- client$get(
      path="search/facebook_posts",
      params=list("surface_ids"=list("282820031228465","339983685122355"))
)

# Search for posts made to specific Page IDs and specific group IDs    

response = client.get(
        path="search/facebook_posts",
        params={"surface_ids": ["282820031228465", "339983685122355"]}
)

Request specific fields

To have the API return only specific fields on any Facebook posts in the response, use the fields parameter and a comma-separated list of fields you want included. If omitted, default fields will be returned. In the following example, only id, text and lang fields are included:

# Return only specific list of fields
response <- client$get(
      path="search/facebook_posts",
      params = list("q"="cybercrime", "fields"="id,text,lang")
)

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

# Return only specific list of fields
response = client.get(
    path="search/facebook_posts",
    params={"q": "cybercrime", "fields": "id,text,lang"}
)
display(response.json()) # Display first page

Search for Facebook posts containing a specific URL

To search for all public posts made to Facebook Pages, profiles, groups, and events that contain specific keywords and a specific URL, use the q and link parameters. The link parameter cannot be used without the q parameter. See Advanced search guidelines for information about how multiple keyword searches are handled.

All forms of the URL that point to the same piece of content will be returned. Searching for multiple URLs in one query is not supported.

# Search including both the `q` and `link` parameters:
response <- client$get(
      path="search/facebook_posts",
      params = list("q"="nike", "link"="https://nike.com")
)

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

# Search including both the `q` and `link` parameters:
        
response = client.get(
    path="search/facebook_posts",
    params={"q": "nike", "link": "https://nike.com"}
)
display(response.json()) # Display first page

Search for posts containing images with the search term

To search for Facebook 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 facebook posts with images containing query term
response <- client$get(
path="search/facebook_posts", 
params=list("q"="example", "search_scope"="post_text_and_image_text")
)

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

Including multimedia in search results: Third-party cleanroom environment 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 Facebook Pages, profiles, groups, and events 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
• Rate limiting and query budgeting for multimedia