Docs · Profile posts

Profile posts

A Facebook Page's or public person's latest posts, newest first, 5 per page.

1 credit per callFresh within 10 minutesMCP tool: facebook_profile_posts

GEThttps://api.lurkapi.com/v1/facebook/profile/posts

When to use this

Pass a profile url (or a numeric pageId) and get the timeline logged-out visitors see: text, time, author, media, link previews, shares and engagement counts. Counts are as the timeline shows them, rounded from 1,000 up; pass a post's url to the post endpoint (facebook_post) for exact counts.

Pagination. 5 posts per page, newest first. Pass cursor back for the next page; it's null on the last page. A profile Facebook won't show logged-out visitors (unknown, or a private person) returns 404 not_found, charged.

Parameters

All parameters go in the query string.

Parameter	Description
`url` stringoptional	A Facebook Page or personal profile URL: a username (https://www.facebook.com/NASA), profile.php?id=, /people/<name>/<id> or /pages/<name>/<id>. Groups, share links and other paths are rejected. Example `https://www.facebook.com/NASA`
`pageId` stringoptional	A numeric Page or profile id, e.g. `100044561550831` (NASA), instead of `url`. Ignored when `url` is set.
`cursor` stringoptional	The `cursor` from the previous response, for the next page.

Example request

Replace YOUR_API_KEY with your key, or set LURKAPI_KEY for the code. Get a free key.

curlJavaScriptPython

JavaScript · reads your key from LURKAPI_KEY

const params = new URLSearchParams({
  url: "https://www.facebook.com/NASA",
});
const res = await fetch(`https://api.lurkapi.com/v1/facebook/profile/posts?${params}`, {
  headers: { "x-api-key": process.env.LURKAPI_KEY },
});
const data = await res.json();
if (!data.success) throw new Error(`${data.code}: ${data.error}`);
console.log(data.posts);

Python · reads your key from LURKAPI_KEY

import os
import requests

res = requests.get(
    "https://api.lurkapi.com/v1/facebook/profile/posts",
    params={
        "url": "https://www.facebook.com/NASA",
    },
    headers={"x-api-key": os.environ["LURKAPI_KEY"]},
    timeout=60,
)
data = res.json()
if not data["success"]:
    raise RuntimeError(f"{data['code']}: {data['error']}")
print(data["posts"])

Example response

A real response from this endpoint, captured from the live API and trimmed to a couple of items. Strings over 96 characters (mostly signed media URLs) are cut short and end in ….

Show the example response (3 KB)

{
  "success": true,
  "credits_remaining": 999999,
  "credits_charged": 1,
  "posts": [
    {
      "post_id": "1658876782274358",
      "url": "https://www.facebook.com/NASA/posts/pfbid0jzaSu71udHuXXhr9dE2wWtP3B23baK…",
      "text": "Float into the weekend... 🪼\n\nLike a space jellyfish! This fuzzy, glowin…",
      "created_at": 1792181102,
      "author": {
        "id": "100044561550831",
        "name": "NASA - National Aeronautics and Space Administration",
        "url": "https://www.facebook.com/NASA"
      },
      "reaction_count": 122000,
      "comment_count": 2100,
      "share_count": 14000,
      "media": [
        {
          "id": null,
          "type": "image",
          "url": null,
          "image_url": "https://scontent-iad6-1.xx.fbcdn.net/v/t39.30808-6/853006520_16588767089…",
          "width": null,
          "height": null,
          "sd_url": null,
          "hd_url": null,
          "duration_s": null
        },
        {
          "id": null,
          "type": "image",
          "url": null,
          "image_url": "https://scontent-iad3-1.xx.fbcdn.net/v/t39.30808-6/853766550_16588767356…",
          "width": null,
          "height": null,
          "sd_url": null,
          "hd_url": null,
          "duration_s": null
        },
        {
          "id": null,
          "type": "image",
          "url": null,
          "image_url": "https://scontent-iad6-1.xx.fbcdn.net/v/t39.30808-6/853155936_16588767389…",
          "width": null,
          "height": null,
          "sd_url": null,
          "hd_url": null,
          "duration_s": null
        }
      ],
      "link": null,
      "shared_post": null
    },
    {
      "post_id": "1658860588942644",
      "url": "https://www.facebook.com/reel/1557618349384047",
      "text": "The aircraft lineup just keeps getting bigger. ✈️\n\nMAX POWER, a new aero…",
      "created_at": 1792179464,
      "author": {
        "id": "100044561550831",
        "name": "NASA - National Aeronautics and Space Administration",
        "url": "https://www.facebook.com/NASA"
      },
      "reaction_count": 1400,
      "comment_count": 52,
      "share_count": 130,
      "media": [
        {
          "id": "1557618349384047",
          "type": "video",
          "url": "https://www.facebook.com/reel/1557618349384047",
          "image_url": "https://scontent-iad3-1.xx.fbcdn.net/v/t15.5256-10/851783682_20368389271…",
          "width": 1080,
          "height": 1920,
          "sd_url": "https://video-iad6-1.xx.fbcdn.net/o1/v/t2/f2/m412/AQMO-eO6K0-N4Kk4gumP3q…",
          "hd_url": "https://video-iad3-1.xx.fbcdn.net/o1/v/t2/f2/m366/AQO8S2aztIKFiQ97H2FGKO…",
          "duration_s": null
        }
      ],
      "link": null,
      "shared_post": null
    }
  ],
  "cursor": "AQHTcGssb13Zu7XXB5f9ECe1ltvos1-qqcSwBUmWUZzhbNOPtTV4vAUWZUdiHiz9bNEWeFni…"
}

Response fields

Every field of a successful response. [] marks a list: a[].b is the b of each item in a. nullable fields can be null; optional fields can be missing.

Show all 38 fields

Field	Type	Description
success	true	Always true here; errors have `success: false`.
credits_remaining	number	Your balance after this call. On anonymous playground calls: free tries left today.
credits_charged	number	Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1).
posts	object[]	Posts, newest first.
posts[].post_id	string	Numeric post id.
posts[].url	string	The post's permalink (a /posts/, /reel/ or /videos/ URL). Pass it to the post endpoint (facebook_post) for exact counts and the reaction breakdown.
posts[].text	stringnullable	The post's text with line breaks; null for a media-only post or a bare share.
posts[].created_at	numbernullable	Publication time as Unix seconds; null when Facebook does not disclose it to public visitors.
posts[].author	object	Who posted it: the Page or person whose timeline this is, or a co-author.
posts[].author.id	stringnullable	Author profile id.
posts[].author.name	stringnullable	Author display name.
posts[].author.url	stringnullable	Author's Facebook URL.
posts[].reaction_count	numbernullable	Total reactions as the timeline shows it: exact below 1,000, rounded from 1,000 up (2.1K is 2100). The post endpoint has exact counts. Null if the timeline leaves it out.
posts[].comment_count	numbernullable	Comments as the timeline shows it: exact below 1,000, rounded from 1,000 up (2.1K is 2100). The post endpoint has exact counts. Null if the timeline leaves it out.
posts[].share_count	numbernullable	Shares as the timeline shows it: exact below 1,000, rounded from 1,000 up (2.1K is 2100). The post endpoint has exact counts. Null if the timeline leaves it out.
posts[].media	object[]	Publicly exposed attached images and videos; delivery URLs can expire.
posts[].media[].id	stringnullable	Media id.
posts[].media[].type	string	Media format.
posts[].media[].url	stringnullable	Facebook media permalink.
posts[].media[].image_url	stringnullable	Image or video thumbnail CDN URL; CDN links expire.
posts[].media[].width	numbernullable	Media width in pixels; null when Facebook does not disclose it to public visitors.
posts[].media[].height	numbernullable	Media height in pixels; null when Facebook does not disclose it to public visitors.
posts[].media[].sd_url	stringnullable	Standard-definition progressive video CDN URL; null for images. CDN links expire.
posts[].media[].hd_url	stringnullable	High-definition progressive video CDN URL; null for images. CDN links expire.
posts[].media[].duration_s	numbernullable	Video duration in seconds; null for images; null when Facebook does not disclose it to public visitors.
posts[].link	objectnullable	The preview card of a link the post shares; null when it shares none.
posts[].link.url	stringnullable	The shared page's URL as the post links it; it can be a short link.
posts[].link.title	stringnullable	The preview's title.
posts[].link.description	stringnullable	The preview's description.
posts[].link.image_url	stringnullable	The preview image, Facebook's CDN copy. CDN links expire.
posts[].shared_post	objectnullable	The post this one shares, as the timeline shows it; null when it isn't a share.
posts[].shared_post.url	stringnullable	The shared post's or photo's permalink.
posts[].shared_post.text	stringnullable	The shared post's text; null when it has none.
posts[].shared_post.created_at	numbernullable	When the shared post was published, as Unix seconds; null when Facebook does not disclose it to public visitors.
posts[].shared_post.author	object	The shared post's author.
posts[].shared_post.author.name	stringnullable	Its author's name.
posts[].shared_post.author.url	stringnullable	Its author's Facebook URL.
cursor	stringnullable	Pass as `cursor` for the next page; null on the last page.

Pagination

Pass the response's cursor back as cursor, with the other parameters unchanged, for the next page. It's null on the last page. Each page costs 1 credit.

The first five pages, in JavaScript

let cursor = null;
for (let page = 1; page <= 5; page++) {
  const params = new URLSearchParams({ url: "https://www.facebook.com/NASA" });
  if (cursor) params.set("cursor", cursor);
  const res = await fetch(`https://api.lurkapi.com/v1/facebook/profile/posts?${params}`, {
    headers: { "x-api-key": process.env.LURKAPI_KEY },
  });
  const data = await res.json();
  if (!data.success) throw new Error(`${data.code}: ${data.error}`);
  console.log(data.posts);
  cursor = data.cursor;
  if (!cursor) break; // last page
}

Caching and freshness

Responses are cached for up to 10 minutes, so a repeat call within that window can return the same data. It still costs 1 credit.

Errors

Errors return { success: false, error, code, docs } with the HTTP status below. Validation errors, 401/402/429 rejections and 5xx failures are free; not_found is charged (how charging works). All error codes.

Status	Code	Meaning
401	`missing_api_key`	No API key. Send it in the `x-api-key` header.
401	`invalid_api_key`	The key is unknown or was revoked.
402	`insufficient_credits`	Not enough credits for this call. Buy a pack or wait for tomorrow's top-up.
403	`account_suspended`	This account is suspended. Contact support@lurkapi.com. Never charged.
404	`not_found`	The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.
405	`method_not_allowed`	Endpoints take GET with query params.
429	`rate_limited`	Too many calls at once. Wait for the `retry-after` seconds, then retry.
500	`internal_error`	Something broke on our side. Retry; 5xx errors are free.
502	`upstream_error`	The platform didn't give a usable answer. Retry; 5xx errors are free.
503	`upstream_busy`	All our connections to the platform are busy. Retry in a few seconds; 5xx errors are free.
504	`upstream_timeout`	The platform took over 30 seconds to answer (90 for web pages). Retry; timeouts are free.

Use it in Claude

Once LurkAPI is connected to Claude, this endpoint is the facebook_profile_posts tool. Ask in plain English, for example:

Ask Claude

Use LurkAPI's facebook_profile_posts with url "https://www.facebook.com/NASA" and summarize what you find.

Claude calls facebook_profile_posts with arguments like these, and each call costs 1 credit:

Tool arguments

{
  "url": "https://www.facebook.com/NASA"
}

Tool results are compact to save tokens: no nulls or empty lists, one URL per image or video, transcripts as plain text unless you pass timestamps=true. A result over 45,000 characters comes in parts: its _note gives the offset for the rest, and later parts are free for 15 minutes. trim=false returns the full response.

From the blog

All posts