OpenAPI Specification
openapi: 3.0.0
info:
description: X API v2 available endpoints
version: '2.166'
title: X API v2 Account Activity News API
termsOfService: https://developer.x.com/en/developer-terms/agreement-and-policy.html
contact:
name: X Developers
url: https://developer.x.com/
license:
name: X Developer Agreement and Policy
url: https://developer.x.com/en/developer-terms/agreement-and-policy.html
servers:
- description: X API
url: https://api.x.com
tags:
- name: News
description: Endpoint for retrieving news stories
externalDocs:
description: Find out more
url: https://developer.twitter.com/en/docs/twitter-api/news
paths:
/2/news/search:
get:
security:
- BearerToken: []
- OAuth2UserToken:
- tweet.read
- users.read
tags:
- News
summary: Search News
description: Retrieves a list of News stories matching the specified search query.
externalDocs:
url: https://docs.x.com/x-api/news/introduction
operationId: searchNews
parameters:
- name: query
in: query
description: The search query.
required: true
example: crypto
schema:
type: string
minLength: 1
maxLength: 2048
example: crypto
style: form
- name: max_results
in: query
description: The number of results to return.
required: false
schema:
type: integer
minimum: 1
maximum: 100
format: int32
default: 10
style: form
- name: max_age_hours
in: query
description: The maximum age of the News story to search for.
required: false
schema:
type: integer
minimum: 1
maximum: 720
format: int32
default: 168
style: form
- $ref: '#/components/parameters/NewsFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Get2NewsSearchResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/2/news/{id}:
get:
security:
- BearerToken: []
- OAuth2UserToken:
- tweet.read
- users.read
- UserToken: []
tags:
- News
summary: Get news stories by ID
description: Retrieves news story by its ID.
externalDocs:
url: https://docs.x.com/x-api/news/introduction
operationId: getNews
parameters:
- name: id
in: path
description: The ID of the news story.
required: true
example: '119929381293'
schema:
$ref: '#/components/schemas/NewsId'
style: simple
- $ref: '#/components/parameters/NewsFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Get2NewsIdResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
components:
schemas:
Get2NewsIdResponse:
type: object
properties:
data:
$ref: '#/components/schemas/News'
errors:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Problem'
Get2NewsSearchResponse:
type: object
properties:
data:
type: array
minItems: 1
items:
$ref: '#/components/schemas/News'
errors:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Problem'
meta:
type: object
properties:
result_count:
$ref: '#/components/schemas/ResultCount'
Problem:
type: object
description: An HTTP Problem Details object, as defined in IETF RFC 7807 (https://tools.ietf.org/html/rfc7807).
required:
- type
- title
properties:
detail:
type: string
status:
type: integer
title:
type: string
type:
type: string
discriminator:
propertyName: type
mapping:
about:blank: '#/components/schemas/GenericProblem'
https://api.twitter.com/2/problems/client-disconnected: '#/components/schemas/ClientDisconnectedProblem'
https://api.twitter.com/2/problems/client-forbidden: '#/components/schemas/ClientForbiddenProblem'
https://api.twitter.com/2/problems/conflict: '#/components/schemas/ConflictProblem'
https://api.twitter.com/2/problems/disallowed-resource: '#/components/schemas/DisallowedResourceProblem'
https://api.twitter.com/2/problems/duplicate-rules: '#/components/schemas/DuplicateRuleProblem'
https://api.twitter.com/2/problems/invalid-request: '#/components/schemas/InvalidRequestProblem'
https://api.twitter.com/2/problems/invalid-rules: '#/components/schemas/InvalidRuleProblem'
https://api.twitter.com/2/problems/noncompliant-rules: '#/components/schemas/NonCompliantRulesProblem'
https://api.twitter.com/2/problems/not-authorized-for-field: '#/components/schemas/FieldUnauthorizedProblem'
https://api.twitter.com/2/problems/not-authorized-for-resource: '#/components/schemas/ResourceUnauthorizedProblem'
https://api.twitter.com/2/problems/operational-disconnect: '#/components/schemas/OperationalDisconnectProblem'
https://api.twitter.com/2/problems/resource-not-found: '#/components/schemas/ResourceNotFoundProblem'
https://api.twitter.com/2/problems/resource-unavailable: '#/components/schemas/ResourceUnavailableProblem'
https://api.twitter.com/2/problems/rule-cap: '#/components/schemas/RulesCapProblem'
https://api.twitter.com/2/problems/streaming-connection: '#/components/schemas/ConnectionExceptionProblem'
https://api.twitter.com/2/problems/unsupported-authentication: '#/components/schemas/UnsupportedAuthenticationProblem'
https://api.twitter.com/2/problems/usage-capped: '#/components/schemas/UsageCapExceededProblem'
NewsId:
type: string
description: Unique identifier of news story.
pattern: ^[0-9]{1,19}$
example: '2244994945'
TweetId:
type: string
description: Unique identifier of this Tweet. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers.
pattern: ^[0-9]{1,19}$
example: '1346889436626259968'
ResultCount:
type: integer
description: The number of results returned in this response.
format: int32
News:
type: object
description: An AI generated news story.
required:
- rest_id
properties:
category:
type: string
description: The news category.
cluster_posts_results:
type: array
items:
type: object
properties:
post_id:
$ref: '#/components/schemas/TweetId'
contexts:
type: object
properties:
entities:
type: object
properties:
events:
type: array
items:
type: string
organizations:
type: array
items:
type: string
people:
type: array
items:
type: string
places:
type: array
items:
type: string
products:
type: array
items:
type: string
finance:
type: object
properties:
tickers:
type: array
items:
type: string
sports:
type: object
properties:
teams:
type: array
items:
type: string
topics:
type: array
items:
type: string
disclaimer:
type: string
hook:
type: string
description: The news hook.
keywords:
type: array
items:
type: string
last_updated_at_ms:
type: string
format: date-time
example: '2025-7-14T04:35:55Z'
name:
type: string
description: The headline.
rest_id:
$ref: '#/components/schemas/NewsId'
summary:
type: string
description: The news summary.
Error:
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
parameters:
NewsFieldsParameter:
name: news.fields
in: query
description: A comma separated list of News fields to display.
required: false
schema:
type: array
description: The fields available for a News object.
minItems: 1
uniqueItems: true
items:
type: string
enum:
- category
- cluster_posts_results
- contexts
- disclaimer
- hook
- id
- keywords
- name
- summary
- updated_at
example:
- category
- cluster_posts_results
- contexts
- disclaimer
- hook
- id
- keywords
- name
- summary
- updated_at
explode: false
style: form
securitySchemes:
BearerToken:
type: http
scheme: bearer
OAuth2UserToken:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://api.x.com/2/oauth2/authorize
tokenUrl: https://api.x.com/2/oauth2/token
scopes:
block.read: View accounts you have blocked.
bookmark.read: Read your bookmarked Posts.
bookmark.write: Create and delete your bookmarks.
dm.read: Read all your Direct Messages.
dm.write: Send and manage your Direct Messages.
follows.read: View accounts you follow and accounts following you.
follows.write: Follow and unfollow accounts on your behalf.
like.read: View Posts you have liked and likes you can see.
like.write: Like and unlike Posts on your behalf.
list.read: View Lists, members, and followers of Lists you created or are a member of, including private Lists.
list.write: Create and manage Lists on your behalf.
media.write: Upload media, such as photos and videos, on your behalf.
mute.read: View accounts you have muted.
mute.write: Mute and unmute accounts on your behalf.
offline.access: Request a refresh token for the app.
space.read: View all Spaces you have access to.
timeline.read: View all Custom Timelines you can see, including public Custom Timelines from other developers.
tweet.moderate.write: Hide and unhide replies to your Posts.
tweet.read: View all Posts you can see, including those from protected accounts.
tweet.write: Post and repost on your behalf.
users.read: View any account you can see, including protected accounts.
UserToken:
type: http
scheme: OAuth