Repository navigation
fix(openapi): lookup reference names post.fields while guides use tweet.fields #503
Description
Summary
The generated post-lookup reference names its optional fields query parameter post.fields, while the expansions guide uses tweet.fields in its examples for post data. This is a separate request-parameter disagreement from the reference-expansion enum: resolving one leaves the other present.
Runtime or environment
Documentation source: current main commit 5fcfe3da51461ef1c0b59a028da9c365547cad4c. The repository has no published releases. The cited live Markdown pages were freshly fetched and compared with this checkout. No live X API calls were made.
Steps to reproduce
- Read the optional fields examples at https://docs.x.com/x-api/fundamentals/expansions.
- Read the field-selection query parameter in https://docs.x.com/x-api/posts/get-post-by-id.
- Resolve the lookup operation parameters in the published https://docs.x.com/openapi.json and compare the name of
PostFieldsParameter.
These document comparisons were executed. No server request was sent with either parameter name.
Expected behavior
The post-lookup reference and guides should consistently name the supported query parameter for selecting fields on returned post objects.
Actual behavior
The guide examples use tweet.fields, including tweet.fields=created_at,public_metrics,conversation_id. The lookup operation references PostFieldsParameter, whose name is post.fields. Its generated published reference preserves that name. Whether the server accepts one or both names was not tested.
Evidence
- Expected source: x-api/fundamentals/expansions.mdx, lines 156–174 uses
tweet.fieldsin post examples. - Failure source: openapi.json, lines 39138–39147 defines
PostFieldsParameterwith namepost.fields;GET /2/tweets/{id}references that component and the published lookup reference renders it. - Evidence provenance: observed
- Local verification: reproduced
- Reproduction completeness: complete
Restoration check
Compare the field-selection parameter name in the guide, the actual lookup operation parameter, and its generated published reference. They should consistently describe the supported request. Establishing server acceptance would require a separate authorized API check; consistency alone must not be described as runtime verification.
Triage assessment
- Impact level: P2
- Assessment status: provisional
- Impact basis: Clients built from the reference and examples receive different request parameter names for post fields. This can lead to missing requested fields or rejected requests, but those server outcomes were not tested, so the impact assessment is provisional.
- Workaround status: unverified
- Workaround basis: The guide offers a different spelling, but neither spelling was tested for this specific query parameter during the investigation.
Activity
shibatashi4ba8-ops commentedon Oct 26, 2026
The same documentation mismatch also affects Recent Search:
https://docs.x.com/x-api/posts/search-recent-posts
https://docs.x.com/x-api/fundamentals/fields
As checked on 2026-10-26, the Recent Search reference lists post.fields, but its enum omits author_id, edit history, and referenced-post metadata. The common Fields guide uses tweet.fields.
In a bounded test on 2026-10-25, GET /2/tweets/search/recent with tweet.fields=author_id,created_at,attachments,edit_history_tweet_ids,referenced_tweets returned HTTP 200 with author IDs, timestamps and edit histories for all 10 returned posts. A separate request for the same posts using post.fields=created_at,attachments returned timestamps and edit_history_post_ids, but no author IDs. The latter did not request author_id, so this is not evidence that an explicit author_id request is unsupported. No user expansions were requested.
Could a maintainer clarify:
Please align the endpoint reference/OpenAPI and the common guide. Successful observations alone do not establish the supported contract. No credentials, post contents or account identifiers are included here.