Truth Social Scraper — Public Posts, Engagement & Account Analytics

Collect public posts from any Truth Social account and get engagement, downvotes, quote posts, media, hashtags, outbound links and posting-time patterns — plus a profile analytics row per account.

Feed it handles, @handles or profile URLs.

---

What it does

1. Captures the metrics that are specific to this platform

Truth Social runs a Mastodon-derived API, but it adds fields vanilla Mastodon has no concept of, and this Actor surfaces them:

• downvoteCount — Truth Social has downvotes. No Mastodon-based scraper reports these, and they change the picture on divisive posts.
• approvalRatioPercent — likes as a share of likes plus downvotes, which only exists because downvotes do.
• isQuotePost — native quote posts, distinguished from plain reposts and from replies.

Alongside them, the standard set: favouriteCount, repostCount, replyCount, totalEngagement and an engagementBand from none up to viral.

2. Content signals pulled out of every post

• postText — HTML flattened to readable text
• hashtags and mentionedAccounts — taken from the API's structured fields, falling back to parsing the text when they are absent
• externalLinks — only links leaving Truth Social. Hashtag and mention links are internal and are excluded, so this field is genuinely "where is this post sending people"
• linkPreviewTitle / linkPreviewUrl from the link card
• mediaCount, mediaTypes, mediaUrls, hasMedia
• isSensitive, contentWarning, language, wordCount

Link targets come from the href attribute rather than the visible text, because long URLs are truncated with invisible spans and the displayed version is unusable.

3. Account analytics, not just a profile dump

Each account gets a record with follower counts and bio plus derived behaviour:

• postsPerDay measured across the collected window
• postTypeBreakdown — original vs reply vs repost vs quote
• postingHourBreakdownUtc — which hours of the day this account posts in, which is a genuinely useful pattern for a high-volume feed
• averageEngagementPerPost and engagementRatePercent against follower count
• topHashtags, topPostUrl, topPostEngagement

Reposts count towards activity but never towards the account's own engagement averages — otherwise resharing a viral post would inflate an account's apparent performance.

---

Input

Field	Type	Default	Description
accountHandles (required)	array	—	Handles, @handles or profile URLs
maxPostsPerAccount	integer	40	Posts collected per account (1–400)
includeReplies	boolean	false	Include replies to other accounts
includeReposts	boolean	true	Include reposts
postedWithinDays	integer	0	Drop older posts; 0 disables
requiredKeywords	array	[]	Keep only posts containing one of these
emitAccountRecords	boolean	true	Emit the per-account analytics row
emitRunSummary	boolean	true	Append the aggregate summary record
concurrentRequests	integer	3	Accounts processed at once
requestTimeoutSec	integer	30	Per-request timeout
proxyConfig	object	disabled	Optional Apify Proxy settings

Example input

{
  "accountHandles": ["realDonaldTrump"],
  "maxPostsPerAccount": 100,
  "includeReplies": false,
  "includeReposts": true,
  "postedWithinDays": 30,
  "requiredKeywords": []
}

---

Output

One post record per post, one account record per handle, then an optional summary.

Post record

{
  "recordType": "post",
  "accountHandle": "realDonaldTrump",
  "postId": "117077744957374868",
  "postUrl": "https://truthsocial.com/@realDonaldTrump/117077744957374868",
  "postType": "original",
  "isRepost": false,
  "isReply": false,
  "isQuotePost": false,
  "postText": "Big announcement about #policy today.",
  "characterLength": 37,
  "wordCount": 5,
  "language": "en",
  "visibility": "public",
  "isSensitive": false,
  "contentWarning": null,
  "postedAt": "2026-08-11T16:10:14.217000+00:00",
  "ageHours": 3.0,
  "postedHourUtc": 16,
  "editedAt": null,
  "favouriteCount": 2837,
  "repostCount": 764,
  "replyCount": 319,
  "downvoteCount": 100,
  "totalEngagement": 3920,
  "engagementBand": "high",
  "approvalRatioPercent": 96.6,
  "hashtags": ["policy"],
  "mentionedAccounts": [],
  "externalLinks": ["https://example.com/story"],
  "linkPreviewTitle": "A news story",
  "linkPreviewUrl": "https://example.com/story",
  "mediaCount": 1,
  "mediaTypes": { "image": 1 },
  "mediaUrls": ["https://static.truthsocial.com/media/img.jpg"],
  "hasMedia": true,
  "matchedKeywords": [],
  "collectedAt": "2026-08-11T19:10:00+00:00"
}

Account record

{
  "recordType": "account",
  "accountHandle": "realDonaldTrump",
  "accountId": "107780257626128497",
  "displayName": "Donald J. Trump",
  "profileUrl": "https://truthsocial.com/@realDonaldTrump",
  "bio": "45th & 47th President of the United States",
  "avatarUrl": "https://static.truthsocial.com/…",
  "headerUrl": "https://static.truthsocial.com/…",
  "followerCount": 12978038,
  "followingCount": 72,
  "totalPostCount": 35641,
  "isVerified": true,
  "isBot": false,
  "isGroup": false,
  "accountCreatedAt": "2022-02-11T16:16:57.705000+00:00",
  "lastPostOn": "2026-08-11",
  "postsAnalyzed": 40,
  "originalPostsAnalyzed": 31,
  "postsPerDay": 12.4,
  "postTypeBreakdown": { "original": 31, "repost": 9 },
  "postingHourBreakdownUtc": { "13": 6, "14": 9, "16": 11, "23": 4 },
  "averageEngagementPerPost": 4182.6,
  "engagementRatePercent": 0.0322,
  "totalEngagementAnalyzed": 167304,
  "topHashtags": ["maga"],
  "topPostUrl": "https://truthsocial.com/@realDonaldTrump/117077744957374868",
  "topPostEngagement": 21873,
  "collectedAt": "2026-08-11T19:10:00+00:00"
}

Summary record

{
  "recordType": "summary",
  "accountsRequested": 1,
  "accountsResolved": 1,
  "lookupsFailed": 0,
  "failedHandles": [],
  "postsCollected": 40,
  "postTypeBreakdown": { "original": 31, "repost": 9 },
  "engagementBandBreakdown": { "very_high": 22, "high": 14, "moderate": 4 },
  "totalEngagement": 167304,
  "averageEngagementPerPost": 4182.6,
  "postsWithMedia": 18,
  "postsWithExternalLinks": 11,
  "topHashtags": [{ "hashtag": "maga", "postCount": 6 }],
  "mostEngagedPostUrl": "https://truthsocial.com/@realDonaldTrump/117077744957374868",
  "mostEngagedPostEngagement": 21873,
  "totalFollowerReach": 12978038,
  "finishedAt": "2026-08-11T19:10:14+00:00"
}

An account that cannot be resolved still produces a row with lookupFailed: true and lookupError.

---

Common use cases

• Media and political monitoring — track what an account posts, when, and how it lands, on a schedule.
• Narrative tracking — requiredKeywords plus topHashtags follows a topic across accounts.
• Engagement benchmarking — engagementRatePercent normalises reach against follower count for fair comparison.
• Link and source analysis — externalLinks and linkPreviewTitle show which outlets an account amplifies.
• Posting-pattern research — postingHourBreakdownUtc reveals daily rhythm and unusual activity windows.
• Archiving — capture public posts with full engagement metrics before they change.

---

Notes and limits

• Only public, unauthenticated endpoints are used. No login happens, and nothing private, follower-only or direct is reachable — this is the same content a signed-out visitor sees.
• Read this before running: Truth Social blocks Apify's IP ranges. Verified on 2026-08-11 against both the datacenter and residential Apify Proxy groups — every request returns 403 from Apify infrastructure, while the identical client is served normally from an ordinary connection. This is an IP-level block, not a header or client-fingerprint problem, and no setting inside this Actor can work around it.
• To run it you must supply your own proxy. proxyConfig accepts custom proxy URLs; point it at a residential or mobile proxy you control. Without one, every row comes back with lookupFailed: true and an error explaining exactly this, rather than silently returning nothing.
• The site additionally fingerprints TLS: with byte-identical headers some HTTP clients are refused and others are served. This Actor uses a client stack verified to be accepted, so if runs fail it is the IP, not the client.
• Engagement counts are a snapshot at collection time and keep moving. Re-run to track change.
• postsPerDay is measured across the collected window only. A small maxPostsPerAccount on a prolific account covers a short window and reads higher than the long-run rate.
• postingHourBreakdownUtc is in UTC, not the account's local time.
• downvoteCount is reported only where the API supplies it; it comes back as 0 rather than null when absent, so treat 0 as "none reported".
• Hashtags and mentions come from the API's structured fields where present, and from text parsing otherwise — the two can differ slightly on older posts.
• Collect and use public posts in line with the platform's terms and applicable law, particularly where posts concern identifiable individuals.

---

Local development

pip install -r requirements.txt
python -m tests.test_core      # 125 checks, including live API calls
apify run