Meta Content Library and API

Guide to Facebook donations data

You can fetch information about donations contributed to a Facebook fundraiser by using the get() method with the facebook/fundraisers/<id>/donations/preview path. This document describes the parameters and shows how to perform basic queries using the method.

Note: Only public donations (privacy set to "everyone") are included. The number of results can therefore be different from the actual number of donations contributed to the fundraiser overall.

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 data fields that are returned.

Parameters

Parameter Type Description

SINCE
Optional

String or Integer

Date in YYYY-MM-DD (date only) or UNIX timestamp (translates to a date and time to the second) format. Facebook donations contributed on or after this date or timestamp are returned (used with UNTIL to define a time range). SINCE and UNTIL are based on UTC time zone, regardless of the local time zone of the user who contributed the donation.

  • If both SINCE and UNTIL are included, the search includes the time range defined by those values.
  • If SINCE is included and UNTIL is omitted, the search includes the SINCE time through the present time.
  • If SINCE is omitted and UNTIL is included, the search goes from the beginning of Facebook time through the UNTIL time.
  • If SINCE and UNTIL are both omitted, the search goes from the beginning of Facebook time to the present time.
  • If SINCE and UNTIL are the same UNIX timestamp, the search includes the SINCE time through the SINCE time plus one hour.
  • If SINCE and UNTIL are the same date (YYYY-MM-DD), the search includes the SINCE date through the SINCE date plus one day.

UNTIL
Optional

String or Integer

Date in YYYY-MM-DD (date only) or UNIX timestamp (translates to a date and time to the second) format. Facebook donations contributed on or before this date or timestamp are returned (used with SINCE to define a time range). SINCE and UNTIL are based on UTC time zone, regardless of the local time zone of the user who contributed the donation.

  • If both SINCE and UNTIL are included, the search includes the time range defined by those values.
  • If SINCE is included and UNTIL is omitted, the search includes the SINCE time through the present time.
  • If SINCE is omitted and UNTIL is included, the search goes from the beginning of Facebook time through the UNTIL time.
  • If SINCE and UNTIL are both omitted, the search goes from the beginning of Facebook time to the present time.
  • If SINCE and UNTIL are the same UNIX timestamp, the search includes the SINCE time through the SINCE time plus one hour.
  • If SINCE and UNTIL are the same Date (YYYY-MM-DD), the search includes the SINCE date through the SINCE date plus one day.

Sample queries

Fetch information about donations made to a Facebook fundraiser

Fetching information about donations made to a specific Facebook fundraiser requires that you first obtain the Meta Content Library ID for the fundraiser by using the get() method with the search/facebook_fundraisers path. The search results will include the ID field by default (you don't have to specify it in your query). See Guide to Facebook fundraisers data to learn about this method. Meta Content Library IDs are unique IDs, each linked to an entity in Meta Content Library. These IDs cannot be used to search on Meta technologies.

Once you have the fundraiser ID, you can use it in the get(path=<fundraiser_id>/donations) method to fetch the donations information.

The following example would return 10 results per page. You can keep calling query_next_page() and has_next_page() to get the next page of 10 results, until all the query results have been returned.

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


client$set_default_version(client$LATEST_VERSION)


# Fetch first 10 donations
response <- client$get(path="<fundraiser-id>/donations/preview")
jsonlite::fromJSON(response$text, flatten=TRUE)


# 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)


# Fetch first 10 donations
response = client.get(path="<fundraiser_id:>/donations/preview")


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

Request donations within a specific time and date range

To have the API return donations within a specific time and date range, create a donations fetch call and pass the since and until parameters you want included.

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


client$set_default_version(client$LATEST_VERSION)


# Will fetch donations that were created after 2025-04-13, 
# but before 1713139200 (epoch timestamp of "2025-04-15 12:00:00 AM")
# Both formats (date and UNIX timestamp) are allowed


response <- client$get(
          path="facebook/fundraisers/<id>/donations/preview",
          params=list("since"="2025-04-13", "until"="1713139200")
)
jsonlite::fromJSON(response$text, flatten=TRUE) # Display first page
from metacontentlibraryapi import MetaContentLibraryAPIClient as client
client.set_default_version(client.LATEST_VERSION)


# Will fetch donations that were created after 2025-04-13, 
# but before 1713139200 (epoch timestamp of "2025-04-15 12:00:00 AM")
# Both formats (date and UNIX timestamp) are allowed


response = client.get(
        path="facebook/fundraisers/<id>/donations/preview", 
        params={'since': '2025-04-14', 'until': '1713139200'}
)
display(response.json()) # Display first page

Learn More