---
title: "Fetch one public post on X (Twitter) by ID or URL. Returns a normalized Post."
method: POST
path: "/v2/ops/social.x.post.get"
tags: ["social/x"]
---

# Fetch one public post on X (Twitter) by ID or URL. Returns a normalized Post.

`POST /v2/ops/social.x.post.get`

## Request

- Base URL: `https://api.agentkey.app`
- URL: `https://api.agentkey.app/v2/ops/social.x.post.get`
- Auth: HTTP bearer

Fetch a single public post on X (Twitter). Pass either the platform-native ID or the post URL; the server extracts the ID and routes to a provider that accepts that input form.

Fixed price: 1 credits per successful call, whichever provider serves it.

## Request body

- object
  - `fields` string[]: Projection: keep only these dotted paths of data, e.g. ["items.id", "items.text"].
  - `id_or_url` string, required: Platform-native post ID or the full post URL.
  - `include_raw` boolean: Attach the raw upstream payload as `raw` (not a stable contract; truncated above 256 KB).
  - `provider` string: Shorthand for routing.only = [provider].
  - `routing` Routing: Provider routing override. order: try these providers first; only: restrict to these (equivalent to pinning); allow_fallbacks: false tries only the first eligible provider.
    - `allow_fallbacks` boolean: false = try only the first eligible provider.
    - `only` string[]: Restrict to these providers.
    - `order` string[]: Providers to try first, in order.
    - `strategy` 'auto': How eligible providers are ordered. auto = the method's curated order. fastest / stable / popular are specified but not implemented yet (400 until then). The price is fixed whatever the strategy; mutually exclusive with order.

## Response `200`

Success envelope

- PostEnvelope: Success envelope whose data is a Post.
  - `attempts` Attempt[], required
    - `error_type` string: validation | not_found | rate_limit | timeout | upstream_unauthorized | upstream_unavailable | provider_error
    - `provider` string, required: Provider slug.
    - `refunded` boolean: true when the reservation for this attempt was refunded.
    - `status` integer, required: HTTP status AgentKey mapped this attempt to (200 on success).
    - `took_ms` integer, required
    - `tool` string, required: Registry tool name (Provider/operation) that was called.
    - `upstream_status` integer: The provider's real HTTP status; absent when nothing was received.
  - `credits_charged` number, required: Credits charged for this call (the method's fixed price).
  - `data` object, required: A public post on a social platform, normalized across providers.
    - `author` object, required
      - `created_at` string, date-time, nullable, required: Account creation time, RFC 3339 UTC. Candidate field (D21).
      - `followers_count` integer, nullable, required: Follower count at crawl time. Candidate field (D21).
      - `handle` string, nullable, required: Username / handle without the leading @.
      - `id` string, nullable, required: Platform-native user ID.
      - `name` string, nullable, required: Display name.
      - `url` string, nullable, required: Profile URL.
      - `verified` boolean, nullable, required: Platform verification badge. Candidate field (D21).
    - `id` string, required: Platform-native post ID.
    - `lang` string, nullable, required: BCP 47 language tag when the platform reports one.
    - `media` object[], nullable, required: Attached media. null when the provider does not expose media at all.
      - `thumbnail_url` string, nullable: Thumbnail / cover URL.
      - `type` 'image' | 'video', required: Media kind.
      - `url` string, nullable, required: Direct media URL (image file or playable video). Null when the platform exposes only a cover for the item (bilibili, WeChat Channels, YouTube) — thumbnail_url still points at that cover.
    - `metrics` object, required: Engagement counters. null means the provider supports the counter but this record has none; a provider that never supplies a counter lists it in unsupported_fields.
      - `bookmarks` integer, nullable, required: Bookmarks.
      - `collects` integer, nullable, required: Collects / favourites (Xiaohongshu-style).
      - `likes` integer, nullable, required: Likes.
      - `quotes` integer, nullable, required: Quote posts.
      - `replies` integer, nullable, required: Replies / comments.
      - `reposts` integer, nullable, required: Reposts / retweets / shares.
      - `views` integer, nullable, required: Views / impressions.
    - `platform` string, required: Platform slug, identical to the one in the method name.
    - `published_at` string, date-time, nullable, required: Publish time, RFC 3339 UTC.
    - `text` string, required: Post text. Includes the title when the platform has one (title, newline, body), so a caller that ignores `title` still sees everything. Empty string when the post has no text body.
    - `title` string, nullable, required: Headline / title when the platform has one (Xiaohongshu notes, bilibili and YouTube videos, Zhihu answers' questions, Reddit and WeChat articles); null on platforms without titles (X, Instagram, TikTok comments).
    - `topic` object, required: Community or board the post belongs to (subreddit, collection). Candidate field (D21).
      - `id` string, nullable, required: Platform-native topic ID.
      - `name` string, nullable, required: Topic display name.
    - `url` string, nullable, required: Canonical URL of the post.
  - `op` string, required: Method name.
  - `op_version` integer, required: Method version that served the call.
  - `provider` string, required: Provider that actually served the call.
  - `raw` unknown
  - `raw_truncated` boolean
  - `request_id` string, required: Correlation id; quote it in support requests.
  - `took_ms` integer, required
  - `unsupported_fields` string[], required: Output paths this provider structurally does not supply; such fields are null for a different reason than 'missing on this record'.

## Other responses

- `400`: Validation error (unknown field, bad cursor, bad routing)
- `402`: Insufficient credits
- `404`: Not found (method, or upstream object)
- `429`: Rate limited upstream
- `502`: All providers failed
- `504`: Timed out

---

[API](https://skmtc.dev/agentkey/apis/agentkey-scenario-methods.md) - [All operations](https://skmtc.dev/agentkey/apis/agentkey-scenario-methods/llms.txt) - [OpenAPI document](https://skmtc.dev/agentkey/apis/agentkey-scenario-methods/revisions/a7cf5b682fdd?raw)