Facebook API Documentation

1. Overview

The API is based on the query language GraphQL. This language is used by Facebook for its APIs, so it is the best way to mimic Graph API. You can get more info by the following links:

GraphQL

Relay Cursor Connections Specification

GraphQL Server Specification

What Extended Facebook API is

It is a set of communication protocols and methods that allows you to form queries to get information on Facebook profiles. Also, it allows you to search for Facebook posts using keywords. Search results can be filtered by location or time period.

The data could be a ground for social media listening, influencer monitoring, customer experience analytics, social media KPIs evaluation, sentiment analysis, competitor benchmarking, brand monitoring, etc.

To learn more, please check our developer documentation and contact us.

What Facebook data you can get

A list of Facebook posts with additional information:

  • detailed engagement info on the post (reactions count, shares count, video views count)
  • post content: text, list of hashtags, list of tagged users
  • basic info on post’s author: full name, username
  • URLs for attachments (images, previews, posts, links, etc.)
  • comments and replies(count, text, reactions, author’s full name, author’s username)

Information about public Facebook profiles:

  • profile type: user, page, group
  • number of friends, followers, members
  • detailed list of the latest publications
  • contacts: address, phone (for public pages only)

2. General info and limitations

We update data only when you request it:

  • If we have it in our database, we will provide the cached version and we’ll start updating the data (to provide the newest data after the second/third request). After each request, you will have all the information that we managed to load till that moment (old data + new data that was downloaded till that moment; or fully new data if loading had been already finished)

  • If we don’t have it in our database, we will send you a message that we are downloading data at this moment. Our server loads data from Instagram to our database. You should repeat the request. You’ll receive the data instead of the message as soon as we’ll finish downloading.

We provide two fields to help understand the “age” of data:

  • last_update. UNIX timestamp when we last updated data in our database;
  • is_being_updated. It’s True if we are in the process of updating. It’s False if it has been already updated.

For the basic pricing plan*:

  • a post is considered updated for 2 hours since the last update
  • a profile is considered updated for 24 hours since the last update
  • we don’t update data if it has been updated less than 2 hours ago. You can get the cached version only
  • we don’t update old posts (older than 1 week) as they get minimal engagement increment

For the basic pricing plan, we load only*:

  • 100 latest posts per hashtag
  • 50 comments per media
  • The first 100 posts from Instagram search results
  • The first 100 posts from Instagram page
*We can change time limits upon request for an additional fee

For the individual plan:

  • We can change the basic plan limits on posts, comments, and pages
  • The search for Facebook events, groups, and pages could be added
  • Extra fields for posts, profiles, comments
  • API customization (request or response formats, webhooks, etc)
  • Demographic data

3. Request format

We use Graph API style for requests. API accepts only GET requests. The access token is provided by us. Facebook API request takes the following form:

GET
https://api.singularex.com/facebook/
<node-type>/<node-ID>
?fields=<graph-request>
&access_token=<your_access_token>

We provide endpoints (node-type) for 5 types of data:

GET
https://api.singularex.com/facebook/
search/<keywords>
?<search-filters>
&fields=<graph-request>
&access_token=<your_access_token>
GET
https://api.singularex.com/facebook/
profile/<profile-ID>
?fields=<graph-request>
&access_token=<your_access_token>
GET
https://api.singularex.com/facebook/
post/<post-ID>
?fields=<graph-request>
&access_token=<your_access_token>
GET
https://api.singularex.com/facebook/
comment/<comment-ID>
?fields=<graph-request>
&access_token=<your_access_token>
GET
https://api.singularex.com/facebook/
reply/<reply-ID>
?fields=<graph-request>
&access_token=<your_access_token>

Certain parameters are required while others are optional. As is standard in URLs, all parameters are separated using the ampersand (&) character.

4. /profile

Graph scheme of the endpoint

Comments and replies:

To enable loading for comments and replies add &load_comments=1 to your query string*.

*Please note that loading a large number of comments may slow down the return response.
Request format:
GET
https://api.singularex.com/facebook/
profile/<profile-ID>
?fields=<graph-request>
&access_token=<your_access_token>
API scheme:
BODY
{
	profile: FacebookProfile {
		id: ID
		username: String
		full_name: String
		profile_type: String
		profile_thumb_url: String # the biggest available pic
		profile_thumb_big_url: String # 50px
		profile_thumb_medium_url: String # 32px
		profile_thumb_small_url: String # 25px
		address: String 
		latitude: Real 
		longitude: Real
		phone: String
		external_url: String 
		like_count: Int
		follower_count: Int
		friend_count: Int
		member_count: Int
		last_update: Int # UNIX timestamp
		is_being_updated: Boolean
		posts: FacebookPostConnection {
			page_info: PageInfo {
				has_next_page: Boolean
				has_previous_page: Boolean
				start_cursor: String
				end_cursor: String
			}
			edges: Edges {
				node: FacebookPost {
					...
					# Same fields as in the facebook.post
					...
				} 
			}
		}
	} 
}

Sample request and response

Profile request
GET
https://api.singularex.com/facebook/
profile/176221562420244
?fields=id,full_name,profile_type,last_update
&access_token=<your_access_token>
Profile response
BODY
{
    "error": {},
    "data": {
        "id": "176221562420244",
        "full_name": "George W. Bush",
        "profile_type": "page",
        "last_update": 1559311418
    },
    "status": "ok"
}

5. /post

Graph scheme of the endpoint

Response filters:

  • from_timestamp, to_timestamp - filter posts by date posted. Format: timestamp
  • from_date, to_date - filter posts by date posted. Format: yyyy-mm-dd

Note:

All filters must be sent as separate GET-params in request URL, for example:
&from_date=2019-06-20&to_date=2019-06-25 or
&from_timestamp=1540000000&to_timestamp=1550000000

Comments and replies:

To enable loading for comments and replies add &load_comments=1 to your query string*.

*Please note that loading a large number of comments may slow down the return response.
Request format:
GET
https://api.singularex.com/facebook/
post/<post-ID>
?fields=<graph-request>
&access_token=<your_access_token>
API scheme:
BODY
{
	post: FacebookPost {
		id: ID
		post_type: String
		created_time: Datetime # ISO 8601 format
		timestamp: Int # UNIX timestamp
		text: String
		tagged_user_text: [ID]
		tags: [String]
		link: String
		link_description: String
		attached_post_id: ID
		attached_media_id: [ID]
		attached_media_preview_url: [String]
		attached_media_preview_content: [String]
		image_url: String
		image_content: String
		video_preview_url: String
		reaction_count: Int
		reaction_like_count: Int
		reaction_love_count: Int
		reaction_haha_count: Int
		reaction_wow_count: Int
		reaction_sad_count: Int
		reaction_angry_count: Int
		share_count: Int
		video_view_count: Int
		last_update: Int # UNIX timestamp
		is_being_updated: Boolean
		owner: FacebookNodeOwner {
			...
			# Same fields as in the in reply.owner
			...
		}
		comments: FacebookCommentConnection {
			page_info: PageInfo {
				has_next_page: Boolean
				has_previous_page: Boolean
				start_cursor: String
				end_cursor: String
			}
			edges: Edges {
				node: FacebookComment {
					...
					# Same fields as in the facebook.comment
					...
				} 
			}
		}
	}  
}

Sample request and response

Post request
GET
https://api.singularex.com/facebook/
post/2764325700276471
?fields=id,post_type,created_time,text,timestamp,tagged_user_text,tags,
reaction_count,reaction_like_count,reaction_love_count,reaction_haha_count,
reaction_wow_count,reaction_sad_count,reaction_angry_count,share_count,
comments.first(3){edges{node{id,timestamp,created_time}}}
&load_comments=1
&access_token=<your_access_token>
Post response
BODY
{
    "error": {},
    "data": {
        "id": "2764325700276471",
        "post_type": "image",
        "created_time": "2019-05-27T17:14:30",
        "text": "Enjoyed a great ride honoring the fallen this morning with fellow grateful citizens, veterans, and first responders.",
        "timestamp": 1558977270,
        "tagged_user_text": [],
        "tags": [],
        "reaction_count": 34000,
        "reaction_like_count": 34000,
        "reaction_love_count": 4300,
        "reaction_haha_count": 0,
        "reaction_wow_count": 66,
        "reaction_sad_count": 0,
        "reaction_angry_count": 0,
        "share_count": 1000,
        "comments": {
            "edges": [
                {
                    "node": {
                        "id": "2764462670262774",
                        "timestamp": 1558915200,
                        "last_update": 1559318406,
                        "is_being_updated": false,
                        "created_time": "2019-05-27T00:00:00"
                    }
                },
                {
                    "node": {
                        "id": "2764427323599642",
                        "timestamp": 1558915200,
                        "last_update": 1559318406,
                        "is_being_updated": false,
                        "created_time": "2019-05-27T00:00:00"
                    }
                },
                {
                    "node": {
                        "id": "2764331096942598",
                        "timestamp": 1558915200,
                        "last_update": 1559318406,
                        "is_being_updated": false,
                        "created_time": "2019-05-27T00:00:00"
                    }
                }
            ]
        }
    },
    "status": "ok"
}

6. /search

Graph scheme of the endpoint

Search filters:

  • author_id - search for posts from the specific user. Format: Facebook profile ID
  • location_id - search for posts with tagged location. Format: Facebook location ID
  • from_date, to_date - filter posts by date posted. Format: yyyy-mm-dd
  • search_type - select search method. Allowed values: top (default value) or latest. On the search page for the latest posts in the FB posts are returned for the last 1-180 minutes, depending on the number of new posts
  • exact_match - additional filtering posts. Your request will return only those posts in which all the elements of the search phrase were found with an exact match. Matches are searched in three blocks: in the post text, in the post link and in the link description. Allowed value: 1. Example: &exact_match=1. Please note that in any case, all posts are downloaded, and then received posts are filtered

Response filters:

  • from_timestamp, to_timestamp - filter posts by date posted. Format: timestamp

Note:

  1. All filters must be sent as separate GET-params in request URL, for example:
    &search_type=top&from_date=2019-06-20&to_date=2019-06-25 or
    &search_type=latest&from_timestamp=1540000000&to_timestamp=1550000000
  2. Do not use search filters from_date and to_date with search_type=latest
  3. Use response filters from_timestamp, to_timestamp instead

Comments and replies:

To enable loading for comments and replies add &load_comments=1 to your query string*.

*Please note that loading a large number of comments may slow down the return response.
Request format:
GET
https://api.singularex.com/facebook/
search/<keywords>
?<search-filters>
&fields=<graph-request>
&access_token=<your_access_token>
API scheme:
BODY
{
	search: FacebookSearch {
		id: ID        
		request: String
		location_id: ID
		author_id: ID
		from_date: Datetime # ISO 8601 format
		to_date: Datetime # ISO 8601 format
		post_count: Int
		last_update: Int # UNIX timestamp
		is_being_updated: Boolean
		posts: FacebookPostConnection {
			page_info: PageInfo {
				has_next_page: Boolean
				has_previous_page: Boolean
				start_cursor: String
				end_cursor: String
			}
			edges: Edges {
				node: FacebookPost {
					...
					# Same fields as in the facebook.post
					...
				} 
			}
		}
	}        
}

Sample request and response

Search request
GET
https://api.singularex.com/facebook/
search/skoda
?fields=id,request,post_count,last_update,is_being_updated,
posts.first(1){edges{node{id,created_time,text,owner{id,full_name}}}}
&location_id=109524955741121
&access_token=<your_access_token>
Search response
BODY
{
    "error": {},
    "data": {
        "id": "skoda/109524955741121/null/null/null/null",
        "request": "skoda",
        "post_count": 100,
        "last_update": 1559308781,
        "is_being_updated": false,
        "posts": {
            "edges": [
                {
                    "node": {
                        "id": "428788844338759",
                        "timestamp": 1559300403,
                        "last_update": 1559308936,
                        "is_being_updated": false,
                        "created_time": "2019-05-31T11:00:03",
                        "text": "Design That Moves!! The ŠKODA RAPID is a masterpiece in design. It stays loyal to the brand’s timeless design ideas while simultaneously incorporating avant-garde elements. For details ☎️ : 7902455555 Visit us at: www.malayalammotorsskoda.co.in #Skoda #Rapid #malayalamSKODA #SkodaDealers",
                        "owner": {
                            "id": "195128237704822",
                            "full_name": "Malayalamskoda"
                        }
                    }
                }
            ]
        }
    },
    "status": "ok"
}

7. /comment

Graph scheme of the endpoint

Request format:
GET
https://api.singularex.com/facebook/
comment/<comment-ID>
?fields=<graph-request>
&access_token=<your_access_token>

Comments and replies:

For correct operation of endpoints /comment and /reply, primarily make a request to download posts containing these comments and replies. You can do this with the endpoints described above (/profile, /post & /search). Please note that to enable the loading of comments and replies you need add &load_comments=1 to your query string*.


*Please note that loading a large number of comments may slow down the return response.
API scheme:
BODY
{
	comment: FacebookComment {
		id: ID
		parent_id: ID
		created_time: Datetime  # ISO 8601 format
		timestamp: Int  # UNIX timestamp
		text: String
		reaction_count: Int
		owner_username: String
		owner_full_name: String
		last_update: Int # UNIX timestamp
		is_being_updated: Boolean
		replies: FacebookCommentReplyConnection {
			page_info: PageInfo {
				has_next_page: Boolean
				has_previous_page: Boolean
				start_cursor: String
				end_cursor: String
			}
			edges: Edges {
				node: FacebookCommentReply {
					...
					# Same fields as in the in facebook.reply
					...
				} 
			}
		}
	}        
}

Sample request and response

Comment request
GET
https://api.singularex.com/facebook/
comment/2764331133609261
?fields=id,parent_id,created_time,timestamp,text,
reaction_count,owner_username,owner_full_name,
replies{edges{node{id,timestamp,created_time}}}
&access_token=<your_access_token>
Comment response
BODY
{
    "error": {},
    "data": {
        "id": "2764331133609261",
        "parent_id": "2764325700276471",
        "created_time": "2019-05-27T00:00:00",
        "timestamp": 1558915200,
        "text": "You never know what ya got, til it's gone. We miss ya Mr. President",
        "reaction_count": 17,
        "owner_username": "ken.boyer.5",
        "owner_full_name": "Ken Boyer",
        "replies": {
            "edges": [
                {
                    "node": {
                        "id": "2764697680239273",
                        "timestamp": 1558915200,
                        "last_update": 1559318406,
                        "is_being_updated": false,
                        "created_time": "2019-05-27T00:00:00"
                    }
                },
                {
                    "node": {
                        "id": "2764595820249459",
                        "timestamp": 1558915200,
                        "last_update": 1559318406,
                        "is_being_updated": false,
                        "created_time": "2019-05-27T00:00:00"
                    }
                }
            ]
        }
    },
    "status": "ok"
}

8. /reply

Graph scheme of the endpoint

Request format:
GET
https://api.singularex.com/facebook/
reply/<reply-ID>
?fields=<graph-request>
&access_token=<your_access_token>
API scheme:
BODY
{
	reply: FacebookCommentReply {
		id: ID
		parent_id: ID
		created_time: Datetime  # ISO 8601 format
		timestamp: Int  # UNIX timestamp
		text: String
		tags: [String]
		reaction_count: Int
		owner_username: String
		owner_full_name: String
		last_update: Int  # UNIX timestamp
		is_being_updated: Boolean
	}
}

Sample request and response

Reply request
GET
https://api.singularex.com/facebook/
reply/2764595820249459
?fields=id,parent_id,created_time,timestamp,text,tags,reaction_count,
owner_username,owner_full_name,last_update,is_being_updated
&access_token=<your_access_token>

Comments and replies:

For correct operation of endpoints /comment and /reply, primarily make a request to download posts containing these comments and replies. You can do this with the endpoints described above (/profile, /post & /search). Please note that to enable the loading of comments and replies you need add &load_comments=1 to your query string*.


*Please note that loading a large number of comments may slow down the return response.
Reply response
BODY
{
    "error": {},
    "data": {
        "id": "2764595820249459",
        "parent_id": "2764331133609261",
        "created_time": "2019-05-27T00:00:00",
        "timestamp": 1558915200,
        "text": "Ken Boyer. That was George Bush Sr. This is Jr.",
        "tags": [],
        "reaction_count": 0,
        "owner_username": "shareen.lasher",
        "owner_full_name": "Shareen Banagan",
        "last_update": 1559318406,
        "is_being_updated": false
    },
    "status": "ok"
}

9. Getting next pages request

To get next pages use page_info’s fields has_next_page, has_previous_page, start_cursor, end_cursor. You can get more info by following the link: Relay Cursor Connections Specification

The has_next_page and has_previous_page values are false in the case when your request displays all available posts. The following endpoints should only be used with restrictions such as posts.first(5) or posts.last(10).

For example, to get the next 5 posts, use the value end_cursor in the endpoint such as posts.first(5).after(“end_cursor”). The end_cursor value is taken from the previous request such as posts.first(5).

To get the previous 5 posts, use the value start_cursor in the endpoint such as posts.last(5).before(“start_cursor”). The start_cursor value is taken from the previous request such as posts.last(5).


Note that the start_cursor and end_cursor values must be in quotes.
Posts request from 1 to 2:
GET
https://api.singularex.com/facebook/
search/mather
?search_type=latest
&fields=id,posts.first(2){
page_info{has_next_page,start_cursor,end_cursor},
edges{node{id}}}
&access_token=<your_access_token>
Posts response from 1 to 2:
BODY
{
    "error": {},
    "data": {
        "id": "mather/null/null/null/null/latest",
        "posts": {
            "page_info": {
                "has_next_page": true,
                "start_cursor": "YXJyYXljb25uZWN0aW9uOjA=",
                "end_cursor": "YXJyYXljb25uZWN0aW9uOjE="
            },
            "edges": [
                {
                    "node": {
                        "id": "2533998059964353",
                        "timestamp": 1560429297,
                        "last_update": 1560429529,
                        "is_being_updated": false
                    }
                },
                {
                    "node": {
                        "id": "2939623566110507",
                        "timestamp": 1560429234,
                        "last_update": 1560429533,
                        "is_being_updated": false
                    }
                }
            ]
        }
    },
    "status": "ok"
}
Posts request from 3 to 4:
GET
https://api.singularex.com/facebook/
search/mather
?search_type=latest
&fields=id,posts.first(2).after("YXJyYXljb25uZWN0aW9uOjE="){
page_info{has_next_page,start_cursor,end_cursor},
edges{node{id}}}
&access_token=<your_access_token>
Posts response from 3 to 4:
BODY
{
    "error": {},
    "data": {
        "id": "mather/null/null/null/null/latest",
        "posts": {
            "page_info": {
                "has_next_page": true,
                "start_cursor": "YXJyYXljb25uZWN0aW9uOjI=",
                "end_cursor": "YXJyYXljb25uZWN0aW9uOjM="
            },
            "edges": [
                {
                    "node": {
                        "id": "724039951400055",
                        "timestamp": 1560429083,
                        "last_update": 1560429530,
                        "is_being_updated": false
                    }
                },
                {
                    "node": {
                        "id": "1580365332095220",
                        "timestamp": 1560428633,
                        "last_update": 1560429528,
                        "is_being_updated": false
                    }
                }
            ]
        }
    },
    "status": "ok"
}

10. Response parameters

Responses are encoded in JSON format and have 3 fields: status, data, and error.

200

If everything is OK (HTTP response: 200 OK or 202 Accepted):

  • status will be ‘ok’ or ‘accepted
  • data field will contain requested data or will be empty if the status is ‘accepted’
Example:
GET
https://api.singularex.com/facebook/
search/london
?fields=post_count
&access_token=<your_access_token>
Response:
BODY
{
    "error": {},
    "data": {
        "post_count": 103
    },
    "status": "ok"
}

Otherwise, if something is not OK:

  • error type will be in the status field
  • data field will be empty
  • error info will be stored in the error field

202

RequestAccepted (HTTP response: 202 Accepted)

Cannot find the requested node in a cache. Starting the parsing process. Repeat request later.

Response:
BODY
{
    "error": {
        "message": "Some nodes you requested are being loaded now: 12345. Try again later",
        "type": "RequestAccepted"
    },
    "data": {},
    "status": "accepted"
}

400

InvalidRequestError (HTTP response: 400 Bad Request)

The graph request is invalid. Repeat request later

Response:
BODY
{
    "error": {
        "message": "Cannot query field \"id_\" on type \"Media\". Did you mean \"id\"?",
        "type": "InvalidRequestError"
    },
    "data": {},
    "status": "InvalidRequestError"
}

403

AuthenticationError (HTTP response: 403 Forbidden)

The access token examination has failed. The access token is not provided or invalid.

Response:
BODY
{
    "error": {
        "message": "Invalid access token",
        "type": "AuthenticationError"
    },
    "data": {},
    "status": "AuthenticationError"
}

404

NodeNotExistsError (HTTP response: 404 Not Found)

A page for the requested node does not exist or cannot be loaded.

Response:
BODY
{
    "error": {
        "message": "Some nodes you requested cannot be loaded: 1690",
        "type": "NodeNotExistsError"
    },
    "data": {},
    "status": "NodeNotExistsError"
}

500

InternalServerError (HTTP response: 500 Internal Server Error)

Something was wrong on our side.

Response:
BODY
{
    "error": {
        "message": "Internal server error",
        "type": "InternalServerError"
    },
    "data": {},
    "status": "InternalServerError"
}
Contact us and get a free trial period
Need help? Don't hesitate to ask us something
Fill in this form and we'll respond to you
You agree with our Terms and Conditions