API technical reference

Introduction

The main URL to access our API is: https://facebook.tracking.exposed/api/v2/.


UserToken is an unique identifier for you Facebook user. It’s a 40-characters long hexadecimal string. You can retrieve it by clicking on “Your Data” when you open Facebook on the browser where you installed the Fbtrex extension. In the URL bar you will find the string. Just copy-paste it.
Paging defines the number of entries that are retrieved by the API, as well as the number of entries to skip. For example, if you call /200-50 at the end of a “Summary” query, you will get 200 entries and skip the 50 most recent ones. If you call /2000-0 you will just get the 2000 most recent entries.

API Index

Name Description URL
Personal Summary link personal/userToken/summary/paging
Personal Stats link personal/userToken/stats/paging
Personal Csv link personal/userToken/csv/paging
Data Exporter link personal/userToken/exporter/paging
Delete your Data link personal/userToken/remove/paging
General Statistics link statistics/counter

Personal Summary

URL

https://facebook.tracking.exposed/api/v2/personal/$YOUR_TOKEN/summary/$AMOUNT-$SKIP

Description

Returns a summary of personal data of an user. $YOUR_TOKEN is your userToken, paging is defined by two integers, $AMOUNT is the number of entries you want to get, $SKIP is how many entries you want to skip.

Data Specifics

Name Description Format Example
impressionTime Time in which the impression was collected/observed. string "2019-04-19T18:06:49.000Z"
impressionOrder Order at which the impression appeared when scrolling the timeline. integer 41
semanticId Unique Id for the impression collected, it's the same in other API feeds such as "semantic". string "7cd2480750f1cdb23215da6da4186b30cbe2f424"
opengraph Provides any available opengraph data for a single impression. Contains the type of link, the link itself, the name of the site, the title of the page and a text description. nested { "fblinktype": "external", "link": "https://elpais.com/internacional/2019/04/18/estados_unidos/1555592324_696739.html", "isValid": true, "siteName": "elpais.com", "title": "El informe sobre la trama rusa revela los intentos de Trump por torpedear la investigación", "description": "Estoy jodido, este es el final de mi presidencia , dijo el mandatario tras el nombramiento de un fiscal especial, según el documento de Robert S. Mueller, hecho público este jueves" }
user Pseudonym for the user that is seeing/collecting the impression. string "gelato-salmon-strawberry"
timeline Pseudonym for the timeline in which the impression appeared. string "pasta-nutella-cabbage"
publicationTime Time at which the post was first published. string "2019-04-18T19:21:01.000Z"
postId Unique ID for the post (not the impression!) string "10125221421413523523"
permaLink Permanent link to the public post. string "/elpais/posts/10156260262981570"
fblinktype Type of media. Can be posts, photos or videos. string "posts"
nature Specifies whether it is a "sponsored" or an "organic" post. string "organic"
images Provides two values: `count` and `captions`. Count returns an integer with the total number of images contained in the impression. Captions contains a list of texts that describe the image (the 'alt' text that appears when you mouseover an image on Facebook.) nested {"count":1,"captions":["Image may contain: one or more people and text"]}
displaySource The full string displayed above the post. string "El País added a new photo."
source The name of the post publisher. string "El País"
sourceLink Link to the profile of the impression publisher. string "https://www.facebook.com/elpais/"
texts List of texts for the impression. Contains translations but not comments. nested [ "\"Estoy jodido, este es el final de mi presidencia\". Es la frase que dijo Trump cuando Robert Mueller se puso a investigar su presunta conexión con Rusia. En sus conclusiones, el fiscal especial recoge esta cita y sus intentos por torpedear la investigación, pero no ve delito", "El informe sobre la trama rusa revela los intentos de Trump por torpedear la investigación", "Estoy jodido, este es el final de mi presidencia , dijo el mandatario tras el nombramiento de un fiscal especial, según el documento de Robert S. Mueller, hecho público este jueves" ]
textsize Length of the text. integer 547
LIKE Number of like reactions. integer 29
HAHA Number of haha reactions. integer 8
ANGRY Number of angry reactions. integer 18
SAD Number of sad reactions. integer 0
LOVE Number of love reactions. integer 0
WOW Number of surprised reactions. integer 0

Sample Usage

Request: https://facebook.tracking.exposed/api/v2/personal/1111a1aa1aa111a11a1a1aa1111a111111a1a1a1/summary/1-0

Response:

[ { "impressionTime": "2019-04-19T18:06:49.000Z", "impressionOrder": 41, "semanticId": "7cd2480750f1cdb23215da6da4186b30cbe2f424", "opengraph": { "fblinktype": "external", "link": "https://elpais.com/internacional/2019/04/18/estados_unidos/1555592324_696739.html", "isValid": true, "siteName": "elpais.com", "title": "El informe sobre la trama rusa revela los intentos de Trump por torpedear la investigación", "description": "Estoy jodido, este es el final de mi presidencia , dijo el mandatario tras el nombramiento de un fiscal especial, según el documento de Robert S. Mueller, hecho público este jueves" }, "user": "taco-tuna-tomato", "timeline": "pepper-flour-shitake", "publicationTime": "2019-04-18T19:21:01.000Z", "postId": "10125221421413523523", "permaLink": "/elpais/posts/10156260262981570", "fblinktype": "posts", "nature": "organic", "images": { "count": 1, "captions": [] }, "displaySource": "El País", "source": "El País", "sourceLink": "https://www.facebook.com/elpais/", "texts": [ "\"Estoy jodido, este es el final de mi presidencia\". Es la frase que dijo Trump cuando Robert Mueller se puso a investigar su presunta conexión con Rusia. En sus conclusiones, el fiscal especial recoge esta cita y sus intentos por torpedear la investigación, pero no ve delito", "El informe sobre la trama rusa revela los intentos de Trump por torpedear la investigación", "Estoy jodido, este es el final de mi presidencia , dijo el mandatario tras el nombramiento de un fiscal especial, según el documento de Robert S. Mueller, hecho público este jueves" ], "textsize": 547, "LIKE": 29, "ANGRY": 18, "HAHA": 8 }


Personal Stats

URL

https://facebook.tracking.exposed/api/v2/personal/$YOUR_TOKEN/stats/$AMOUNT-$SKIP

Description

Returns a list of timelines for the user, including a count for the number of impression and all the data contained in summary. $YOUR_TOKEN is your userToken, paging is defined by two integers, $AMOUNT is the number of entries you want to get, $SKIP is how many entries you want to skip.

Data Specifics

Name Description Format Example
storedTimelines Number of total timelines for the user. integer 1045
served Specifies the values for paging with which the API was called. integer { "amount": 1, "skip": 1 }
content Contains a list of posts, with the startTime of the timeline, the country of the user, the impressionOrder, impressionTime, htmlId and timelineId, as well as a summary with the same information as the "summary" API. { "startTime": "2019-05-02T08:33:40.000Z", "geoip": "ES", "impressionOrder": 1, "impressionTime": "2019-05-02T08:33:40.000Z", "htmlId": "xxx", "timelineId": "yyy", "summary": [] }, {...}
timelines List of timeline IDs with the number of impressions collected per ID. { "timelinexxxxyyyy": 12, "timelineyyyyyyyzzzzzz" 65

Sample Usage

Request: https://facebook.tracking.exposed/api/v2/personal/userToken/stats/1-0

Response:

{ "storedTimelines": 31, "served": { "amount": 1, "skip": 1 }, "content": [ { "startTime": "2019-05-02T08:33:40.000Z", "geoip": "UK", "impressionOrder": 1, "impressionTime": "2019-05-02T08:33:40.000Z", "htmlId": "83489349sdfsfas907395923502352332", "timelineId": "ac11229201721912aa129128192aa", "summary": [] }, { "startTime": "2019-05-02T08:33:40.000Z", "geoip": "UK", "impressionOrder": 2, "impressionTime": "2019-05-02T08:33:40.000Z", "htmlId": "83489349sdfsfas907395923502352332", "timelineId": "ac11229201721912aa129128192aa", "summary": [] } ], "timelines": { "ac11229201721912aa129128192aa": 12 } }


Personal Csv

URL

https://facebook.tracking.exposed/api/v2/personal/$YOUR_TOKEN/csv/$AMOUNT-$SKIP

Description

Returns a comma-separated-values file containing personal data of an user. $YOUR_TOKEN is your userToken. Paging is defined by two integers, $AMOUNT is the number of entries you want to get, $SKIP is how many entries you want to skip.

Data Specifics

Name Description Format Example
nature Specifies whether it is a "sponsored" or an "organic" post. string "organic"
publicationTime Time at which the post was first published. string "2019-04-18T17:21:30.000Z"
postId Unique ID for the post (not the impression!) string "1247146142126177"
permaLink Permanent link to the public post. string "/CatalunyaDiari/posts/1247146142126177"
fblinktype Type of media. Can be posts, photos or videos. string "posts"
source The name of the post publisher. string "Catalunya Diari"
sourceLink Link to the profile of the impression publisher. string "https://www.facebook.com/CatalunyaDiari/"
displaySource The full string displayed above the post. string "Catalunya Diari"
textsize Length of the text. integer 171
texts List of texts for the impression. Contains translations but not comments. nested [ "Hello world.", "Also this." ]
impressionTime Time in which the impression was collected/observed. string "2019-04-21T15:05:15.000Z"
impressionOrder Order at which the impression appeared when scrolling the timeline. integer 14
user Pseudonym for the user that is seeing/collecting the impression. string "goulash-nocilla-cucumber"
timeline Pseudonym for the timeline in which the impression appeared. string "onion-couscous-strawberry"
semanticId Unique Id for the impression collected, it's the same in other API feeds such as "semantic". string "82a416a63569d1b65ddfae1ff5b5812b13a247cf"

Sample Usage

Request: https://facebook.tracking.exposed/api/v2/personal/1111a1aa1aa111a11a1a1aa1111a111111a1a1a1/csv/1-0

Response: "nature","publicationTime","postId","permaLink","fblinktype","source","sourceLink","displaySource","textsize","texts","impressionTime","impressionOrder","user","timeline","semanticId" "organic","2019-04-18T17:21:30.000Z","1247146142126177","/CatalunyaDiari/posts/1247146142126177","posts","Catalunya Diari","https://www.facebook.com/CatalunyaDiari/","Catalunya Diari","171"," ‖▩‖ ","2019-04-21T15:05:15.000Z","14","goulash-nocilla-cucumber","onion-couscous-strawberry","82a416a63569d1b65ddfae1ff5b5812b13a247cf"


Export your Data

URL

https://facebook.tracking.exposed/api/v2/personal/$YOUR_TOKEN/exporter/$PAGING

Description

Returns all the data you own on our platform. $YOUR_TOKEN is your userToken.

Data Specifics

TBD

Sample Usage

Request: https://facebook.tracking.exposed/api/v2/personal/1111a1aa1aa111a11a1a1aa1111a111111a1a1a1/exporter/


Delete your Data

URL

https://facebook.tracking.exposed/api/v2/personal/$YOUR_TOKEN/remove/$PAGING

Description

Removes the data you own on our platform. $YOUR_TOKEN is your userToken. The output will confirm that your data has been deleted.

Data Specifics

TBD

Sample Usage

Request: https://facebook.tracking.exposed/api/v2/personal/1111a1aa1aa111a11a1a1aa1111a111111a1a1a1/remove/5

Response:
{"timelines":5,"impressions":63,"htmls":35,"summaries":35}


General Statistics

URL

https://facebook.tracking.exposed/api/v2/statistics/counter

Description

General statistics on facebook.tracking.exposed. Contains global and last week’s information. Please note that the fields that terminate in _lw are for last week.

Data Specifics

TBD

Sample Usage

Request: https://facebook.tracking.exposed/api/v2/statistics/counter

Response:
{"content":{"impressions":15614360,"impressions_lw":162084,"aggregated":2673,"aggregated_lw":140,"labels":87946,"labels_lw":87946,"semantics":625307,"semantics_lw":625307,"anomalies":0,"anomalies_lw":0,"summary":1741653,"summary_lw":89911,"errors":52708,"errors_lw":52708,"metadata":1747629,"metadata_lw":89938,"htmls":9767659,"htmls_lw":110072,"accesses":215408,"accesses_lw":974,"timelines":1207216,"timelines_lw":12826,"supporters":3486,"supporters_lw":13},"computedt":"2019-04-23T13:53:34.254Z","next":"2019-04-23T13:55:34.254Z","cacheTimeSeconds":120}