# Trawline

> Social-media data API for agents and developers. Public, logged-out data only. Stable, versioned JSON (v1). Every credit price is a config fact; every uptime number is measured, not promised.

Base URL: https://trawline.dev
Auth: `Authorization: Bearer trw_...` (API key). The data API never uses cookies.
Free tier: 30 credits on signup.

## Endpoints
- **Profile** `POST /api/v1/{platform}/profile` — 1 credit. Platforms: youtube, tiktok, instagram, facebook, x, twitch, threads.
- **Stats** `POST /api/v1/{platform}/stats` — 1 credit. Platforms: youtube, tiktok, instagram, facebook, x, twitch, threads.
- **Comments** `POST /api/v1/{platform}/comments` — 1 credit. Platforms: youtube, tiktok, instagram, facebook, twitch.
- **Channel Stats** `POST /api/v1/{platform}/channel_stats` — 1 credit. Platforms: youtube, tiktok, instagram, facebook, twitch.
- **Channel Posts** `POST /api/v1/{platform}/channel_posts` — 1 credit. Platforms: instagram, facebook.
- **Channel Reels** `POST /api/v1/{platform}/channel_reels` — 1 credit. Platforms: instagram.
- **Channel Videos** `POST /api/v1/{platform}/channel_videos` — 1 credit. Platforms: youtube, tiktok, facebook, twitch.
- **Channel Clips** `POST /api/v1/{platform}/channel_clips` — 1 credit. Platforms: twitch.
- **Tweets** `POST /api/v1/{platform}/tweets` — 1 credit. Platforms: x.
- **Transcript** `POST /api/v1/{platform}/transcript` — 1 credit per started minute. Platforms: youtube, tiktok, instagram, facebook, x, twitch.
- **Summarize** `POST /api/v1/{platform}/summarize` — 2 credits. Platforms: youtube, tiktok, instagram, facebook, x, twitch.
- **Search** `POST /api/v1/{platform}/search` — 2 credits. Platforms: youtube, tiktok, instagram, facebook, twitch.
- **Hashtag Search** `POST /api/v1/{platform}/hashtag_search` — 2 credits. Platforms: tiktok.
- **Trends** `POST /api/v1/{platform}/trends` — 2 credits. Platforms: youtube.

## Billing (free, 0 credits)
- **Credit balance** `GET /api/v1/account/credits` — your remaining credits. Zero is a real answer, never a placeholder.
- **Request receipt** `GET /api/v1/billing/receipts/{receipt_id}` — what one call did to your credits. The id is the `x-request-id` header on the response you are asking about.

## Platform-specific fields
- **Profile — Twitch only**: `createdAt`, `isPartner`, `isAffiliate`, `profileImageUrl`, `bannerImageUrl`, `team`, and `socialLinks` (the channel's own links to other major public platforms, each as `{platform, url}`). Links to other destinations are not returned; when any were dropped the response says how many.
- **Channel Stats — Twitch only**: `videoCount`, `isLive`, `live` (`title`, `viewers`, `game`, `startedAt`, `language`) and `latestBroadcast`. Live figures change minute to minute; each answer is a snapshot taken at `fetchedAt`. On Twitch `subscriberCount` is the public FOLLOWER count — Twitch publishes no paid-subscriber total to public requests, and every response says so in a note.
- Any field a platform does not publish is omitted, never filled with a placeholder.

## For agents
- OpenAPI 3.1: https://trawline.dev/openapi.json
- MCP tool discovery: https://trawline.dev/.well-known/mcp.json
- Live reliability: https://trawline.dev/api/status (machine-readable; check before depending on a cell)

## Maturity
5 of 52 services Live across 2 platforms.

## Rules we keep
- Public/logged-out data only. No accounts, logins, or paywalled content.
- We request no contact-detail fields. Free text (bios, captions, comments) is returned as the platform published it, so it may contain contact details the author chose to publish.
- AI summaries are labeled opinion, never asserted as fact.