Content Library and API

Share API search ID

You can perform a search in Meta Content Library and capture the query with its search parameters so you can perform the same search in Content Library API. You do this by requesting an API search ID in Content Library and then passing that ID in Content Library API. The API search ID functions as an alias of the search with all its parameters. Some key points about this feature:

  • The format of the API search ID generated by Content Library is the current date followed by a randomly generated string of characters. For example, 2024-10-12-iehs.

  • Only the query and search parameters are saved and represented by the API search ID, not the search results.

  • You can share API search IDs with other individuals, as long as they have the same account type that you have.

  • This feature is available for post search endpoints for Facebook and Instagram, including synchronous and asynchronous searches.

In Content Library API, you can:

  • Perform the search represented by the API search ID.

  • View the filters applied within a search represented by an ID.

  • Use an ID but override individual filters with new values.

Obtain an API search ID in Content Library

To obtain an API search ID:

  1. In Content Library, select filters and values and perform your search.

  2. Click the Create API search ID button in the top menu bar (hover over the buttons to see their names).

  3. The API search ID is displayed along with the filters associated with the ID and some instructions for use in the API.

You can also create an API search ID from a previously saved search:

  1. In Content Library, go to your Saved searches page.

  2. Click the More button (...) corresponding to the saved search.

  3. Click Create API search ID.

Use an API search ID in Content Library API

Perform the same search in the API

Once you have the API search ID that was generated in Content Library, you can perform the same search in the API by calling the appropriate post search endpoint, one of the following:

  • /search/facebook_posts/{alias_id}
  • /async_search/facebook_posts/{alias_id}

You would use the corresponding Instagram post search endpoints for shared searches that originated in Instagram.

Pass the API search ID (alias_id) in the call. The filters associated with the ID are applied and are reflected in the response. For example:

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

client$set_default_version(client$LATEST_VERSION)

response <- client$get(
        path="search/facebook_posts/2024-11-05-grdy"
)
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/2024-11-05-grdy"
)
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

View the search details represented by an ID

To see the filters and values associated with an ID, call the /collections/shared_search/{alias_id} endpoint and pass the API search ID that was generated in Content Library. For example:

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

client$set_default_version(client$LATEST_VERSION)

response <- client$get(
        path="collections/shared_search/2024-11-05-grdy",
)
jsonlite::fromJSON(response$text, flatten=TRUE)
from metacontentlibraryapi import MetaContentLibraryAPIClient as client

client.set_default_version(client.LATEST_VERSION)

response = client.get(
    path="collections/shared_search/2024-11-05-grdy",
)
display(response.json())

See Data dictionary for data included in responses.

Use an ID but override individual parameters

To begin with the search represented by an ID but modify it somewhat, call the appropriate post search endpoint along with the ID, and then append any new parameters. For example, you could change search keywords and the sort order like this:

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

client$set_default_version(client$LATEST_VERSION)

response <- client$get(
        path="search/facebook_posts/2024-11-06-vdoj",
        params = list("q"="cybercrime","sort"="newest_to_oldest")
)
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/2024-11-06-vdoj",
    params={"q": "cybercrime","sort":"newest_to_oldest"}
)
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