Endpoints related to retrieving usage — 2 operation(s) in the X-published contract.
Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/x:x-usage-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
description: X API v2 core endpoints
version: '2.168'
title: X API v2 Usage 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: Usage
description: Endpoints related to retrieving usage
externalDocs:
description: Find out more
url: https://docs.x.com/x-api/usage/introduction
paths:
/2/usage/credits:
get:
security:
- OAuth2UserToken: []
- BearerToken: []
tags:
- Usage
summary: Get usage credits
description: Returns the payer's developer-platform credit balance in USD. total_balance is max(0, prepaid_balance + free_balance); prepaid_balance may be negative.
operationId: getUsageCredits
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/GetUsageCreditsResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/2/usage/tweets:
get:
security:
- BearerToken: []
tags:
- Usage
summary: Get Usage
operationId: getUsage
parameters:
- name: days
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 90
format: int32
default: 7
style: form
- $ref: '#/components/parameters/UsageFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/GetUsageResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
components:
schemas:
Usage:
type: object
properties:
cap_reset_day:
type: integer
daily_client_app_usage:
$ref: '#/components/schemas/UsageDailyClientAppUsage'
daily_project_usage:
$ref: '#/components/schemas/UsageDailyProjectUsage'
project_cap:
type: string
project_id:
type: string
project_usage:
type: string
Error:
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
InvalidRequestProblem:
type: object
required:
- type
- title
- detail
properties:
detail:
type: string
parameter:
type: string
status:
type: integer
title:
type: string
type:
type: string
enum:
- https://api.x.com/2/problems/invalid-request
value:
type: string
ResourceUnavailableProblem:
type: object
required:
- type
- title
- detail
- resource_type
properties:
detail:
type: string
resource_id:
type: string
resource_type:
type: string
status:
type: integer
title:
type: string
type:
type: string
enum:
- https://api.x.com/2/problems/resource-unavailable
ResourceNotFoundProblem:
type: object
required:
- type
- title
- detail
- resource_type
properties:
detail:
type: string
parameter:
type: string
resource_id:
type: string
resource_type:
type: string
status:
type: integer
title:
type: string
type:
type: string
enum:
- https://api.x.com/2/problems/resource-not-found
value:
type: string
FieldHydrationFailureProblem:
type: object
required:
- type
- title
- detail
- field
properties:
detail:
type: string
field:
type: string
resource_type:
type: string
section:
type: string
status:
type: integer
title:
type: string
type:
type: string
enum:
- https://api.x.com/2/problems/field-hydration-failure
GetUsageResponse:
type: object
properties:
data:
$ref: '#/components/schemas/Usage'
errors:
type: array
items:
$ref: '#/components/schemas/Problem'
FieldUnauthorizedProblem:
type: object
required:
- type
- title
- detail
- field
properties:
detail:
type: string
field:
type: string
resource_type:
type: string
section:
type: string
status:
type: integer
title:
type: string
type:
type: string
enum:
- https://api.x.com/2/problems/field-unauthorized
UsageDailyProjectUsage:
type: object
description: Project-level daily Post usage for the caller's project.
properties:
project_id:
type:
- string
- 'null'
description: Unique identifier of the project.
usage:
type:
- array
- 'null'
description: Daily usage entries for the project.
items:
type: object
description: A single day's usage entry.
required:
- date
properties:
date:
type: string
description: The day of the usage entry, as an ISO 8601 date-time.
usage:
type:
- string
- 'null'
description: Number of Posts used on this day.
DisallowedResourceProblem:
type: object
required:
- type
- title
- detail
properties:
detail:
type: string
resource_id:
type: string
resource_type:
type: string
section:
type: string
status:
type: integer
title:
type: string
type:
type: string
enum:
- https://api.x.com/2/problems/disallowed-resource
UsageDailyClientAppUsage:
type: array
description: Per-client-app daily Post usage for the caller's project.
items:
type: object
description: Per-client-app daily Post usage entry.
required:
- usage_result_count
properties:
client_app_id:
type:
- string
- 'null'
description: Unique identifier of the client app.
usage:
type: array
description: Daily usage entries for this client app.
items:
type: object
description: A single day's usage entry.
required:
- date
properties:
date:
type: string
description: The day of the usage entry, as an ISO 8601 date-time.
usage:
type:
- string
- 'null'
description: Number of Posts used on this day.
usage_result_count:
type: integer
description: Number of daily usage entries returned for this client app.
format: int64
Problem:
oneOf:
- $ref: '#/components/schemas/ResourceNotFoundProblem'
- $ref: '#/components/schemas/InvalidRequestProblem'
- $ref: '#/components/schemas/NotAuthorizedForResourceProblem'
- $ref: '#/components/schemas/NotAuthorizedForFieldProblem'
- $ref: '#/components/schemas/FieldUnauthorizedProblem'
- $ref: '#/components/schemas/FieldHydrationFailureProblem'
- $ref: '#/components/schemas/ResourceUnavailableProblem'
- $ref: '#/components/schemas/DisallowedResourceProblem'
- $ref: '#/components/schemas/InternalErrorProblem'
discriminator:
propertyName: type
mapping:
https://api.x.com/2/problems/disallowed-resource: '#/components/schemas/DisallowedResourceProblem'
https://api.x.com/2/problems/field-hydration-failure: '#/components/schemas/FieldHydrationFailureProblem'
https://api.x.com/2/problems/field-unauthorized: '#/components/schemas/FieldUnauthorizedProblem'
https://api.x.com/2/problems/internal-error: '#/components/schemas/InternalErrorProblem'
https://api.x.com/2/problems/invalid-request: '#/components/schemas/InvalidRequestProblem'
https://api.x.com/2/problems/not-authorized-for-field: '#/components/schemas/NotAuthorizedForFieldProblem'
https://api.x.com/2/problems/not-authorized-for-resource: '#/components/schemas/NotAuthorizedForResourceProblem'
https://api.x.com/2/problems/resource-not-found: '#/components/schemas/ResourceNotFoundProblem'
https://api.x.com/2/problems/resource-unavailable: '#/components/schemas/ResourceUnavailableProblem'
InternalErrorProblem:
type: object
required:
- type
- title
- detail
properties:
detail:
type: string
status:
type: integer
title:
type: string
type:
type: string
enum:
- https://api.x.com/2/problems/internal-error
NotAuthorizedForResourceProblem:
type: object
required:
- type
- title
- detail
- resource_type
properties:
detail:
type: string
parameter:
type: string
resource_id:
type: string
resource_type:
type: string
section:
type: string
status:
type: integer
title:
type: string
type:
type: string
enum:
- https://api.x.com/2/problems/not-authorized-for-resource
value:
type: string
GetUsageCreditsResponse:
type: object
properties:
data:
$ref: '#/components/schemas/GetUsageCreditsResponseData'
errors:
type: array
items:
$ref: '#/components/schemas/Problem'
GetUsageCreditsResponseDataFreeGrants:
type: object
required:
- amount
properties:
amount:
type: number
description: USD remaining in this free grant.
expires_at:
type: string
description: When this grant expires (RFC 3339). Omitted if the grant never expires or the expiry is unknown.
additionalProperties: false
NotAuthorizedForFieldProblem:
type: object
required:
- type
- title
- detail
- field
properties:
detail:
type: string
field:
type: string
parameter:
type: string
resource_id:
type: string
resource_type:
type: string
section:
type: string
status:
type: integer
title:
type: string
type:
type: string
enum:
- https://api.x.com/2/problems/not-authorized-for-field
value:
type: string
GetUsageCreditsResponseData:
type: object
required:
- total_balance
- prepaid_balance
- free_balance
- free_grants
properties:
free_balance:
type: number
description: USD remaining across unexpired free grants.
free_grants:
type: array
description: Unexpired free grants, soonest expiry first.
items:
$ref: '#/components/schemas/GetUsageCreditsResponseDataFreeGrants'
prepaid_balance:
type: number
description: Purchased (prepaid) USD balance. May be negative when paid usage has overdrawn this bucket.
total_balance:
type: number
description: 'Spendable USD remaining, clamped at 0.00: total_balance = max(0, prepaid_balance + free_balance).'
parameters:
UsageFieldsParameter:
name: usage.fields
in: query
description: A comma separated list of Usage fields to display.
required: false
schema:
type: array
description: The fields available for a Usage object.
minItems: 1
uniqueItems: true
items:
type: string
enum:
- cap_reset_day
- daily_client_app_usage
- daily_project_usage
- project_cap
- project_id
- project_usage
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.
block.write: Block and unblock accounts on your behalf.
bookmark.read: Read your bookmarked Posts.
bookmark.write: Create and delete your bookmarks.
broadcast.read: View your live broadcasts and their chat.
broadcast.write: Manage your live broadcasts and send chat messages on your behalf.
developer.read: View your developer accounts, apps, and settings.
developer.write: Create and manage your X Developer Platform account.
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.
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: Create and repost on your behalf.
users.read: View any account you can see, including protected accounts.
UserToken:
type: http
scheme: OAuth