X API Playground: the free local mock, and its limits

#Quick answer

X API Playground is a free local server, published by X itself, that pretends to be the X API v2. You install a Go binary, run playground start, point your code at http://localhost:8080, and every request your integration makes during development is answered locally instead of billed. It is the cheapest fix for the single biggest change to this platform in 2026: there is no free tier any more, so every careless loop in a test suite costs money.

Last updated: October 2026

Almost nobody uses it, and that is mostly X's fault. The tool got one forum post on 23 December 2025 and one card on the Tools and Libraries page. It has no page in the developer documentation, no entry in llms.txt, and no mention in the pay-per-use announcements where it would have been most useful.

#What it actually is

A single Go binary that serves an HTTP API shaped like api.x.com, with in-memory state, seeded data, and a browser UI.

go install github.com/xdevplatform/playground/cmd/playground@latest
playground start
curl -H "Authorization: Bearer test" http://localhost:8080/2/users/me

Setup ends there. Go 1.21 or later is the only prerequisite. The web UI opens at http://localhost:8080/playground, and alongside the emulated X routes the server exposes its own management endpoints: GET /health, GET /endpoints, POST /state/reset, GET /state/export, POST /state/import and GET /rate-limits.

State is real in the sense that matters. Create a Post against the playground and a later read returns it. Enable persistence in ~/.playground/config.json and that state survives a restart, which is what makes it usable in a CI pipeline where a fixture has to exist before the test that reads it.

Two simulations are switched off by default and worth turning on deliberately. Rate limiting (rate_limit.enabled) returns a real 429 with x-rate-limit-limit, x-rate-limit-remaining and x-rate-limit-reset headers once the window fills. Error injection (errors.enabled, with an error_rate between 0 and 1) makes a configurable share of requests fail, which is the only cheap way to find out whether your retry logic actually retries.

#Why the frozen repo still tracks the live API

Commit history on the repo looks abandoned. Four releases between 23 December 2025 and 9 January 2026, ending at v1.2.1, and nothing since. Five open issues, the newest from June 2026, none answered.

That matters less than it looks, because the playground does not hardcode its routes. On first start it downloads https://api.x.com/2/openapi.json, caches it at ~/.playground/.playground-openapi-cache.json, and re-downloads it whenever the cache is older than 24 hours. playground refresh forces it. The DOCUMENTATION.md description is blunt about the consequence: the server "automatically supports new endpoints as they're added to the spec."

So the routing layer and the request validation layer are current. What froze in January is the hand-written part: the seeded data model, the response construction, and the error bodies. The result is a tool that will happily accept a request to an endpoint that shipped last month and answer it with something generic.

If you want the genuinely current picture of which endpoints exist and what they do, the spec itself and X API search are better references than anything the playground returns.

#The cost meter is the actual reason to run it

Version 1.2.0 added usage and cost tracking, and this is the feature that justifies the install.

Every successful request is metered against X's own rate card, and the result is exposed at three endpoints:

curl http://localhost:8080/api/credits/pricing | jq
curl "http://localhost:8080/api/accounts/0/usage?interval=30days&groupBy=eventType" | jq
curl http://localhost:8080/api/accounts/0/cost | jq

Those rates are not guesses. credits.go sets pricingURL to https://console.x.com/api/credits/pricing and fetches it with a 24-hour cache, falling back to a hardcoded table only when the fetch fails. That endpoint is public, it answers an unauthenticated curl, and on 18 October 2026 it returns the live list: Post at $0.005 per resource, User and Follow and DirectMessage at $0.010, Like and Mute and Block and OwnedRead at $0.001, and on the write side PostCreate at $0.015, UserInteractionCreate at $0.015, and ContentCreateWithUrl at $0.200.

That last one deserves a second look. Creating a Post that contains a link is priced at twenty cents a request, forty times a plain Post create. X's pricing page lists it as "Post: Create (with URL)". A scheduler that posts 50 links a day is spending $300 a month on write calls alone, which is the kind of number you want to discover in a local meter rather than in a Developer Console invoice. The rest of the rate card, including the $20 and $50 free credit incentives X added on 2 October 2026, is in our X API pricing breakdown.

Metering also copies a billing rule most developers miss. Read charges are per resource, and X deduplicates a resource within a 24-hour UTC window, so fetching the same Post twice in a day is billed once. The playground implements the same 24-hour window against the resource IDs in the response body, which means a pagination loop that re-reads overlapping pages prices correctly instead of looking twice as expensive as it is.

#Where the emulation stops matching the real API

Open issues on the repo are a decent map of the gaps, and they are specific.

Issue #3 is the one to internalise. The playground returns an error, but not X's error, so a test that asserts on errors[0].parameters passes locally and fails in production. Anything that depends on exact failure shapes has to be verified against the real API at least once.

Two more things it does not do. There is no OAuth flow: authentication is accepted, not performed, and the bearer token you send is used to derive an account ID rather than validated. And the repo has no LICENSE file despite the README saying MIT, which may matter if your employer's policy checks for one.

#When to use it, and when to spend real credits

Use the playground for the work that is expensive precisely because it is repetitive: wiring a client, iterating on pagination, shaping a database around response payloads, running integration tests on every commit, and estimating what a feature will cost before you ship it.

Spend real credits for anything where fidelity is the thing under test. Auth flows need the real token exchange, which is covered in X API OAuth. Media upload needs real multipart handling. Rate-limit behaviour under genuine concurrency needs the real limiter. Error handling needs at least one pass against real error bodies.

A sensible split is a single environment variable for the base URL, defaulting to http://localhost:8080 in development and CI and https://api.x.com in a staging job that runs on merge rather than on every push. That gives you the fast free loop most of the time and a real check before anything reaches production.

Worth knowing what the playground is not competing with. It is a mock, not an access route, so it does nothing about the parts of X that the API has not covered since the 2026 restrictions. If what you actually need is an account that posts and replies on your behalf rather than a server that pretends to, that is a different category of tool: X-Autopilot runs in your own browser on your own machine instead of calling endpoints that no longer sell what you want. And if you are wiring a model into X rather than a service, the X MCP server is the path X does support.

#Getting a key first

No credentials are needed to run the playground, which makes it a good place to start before you have any. When you do need the real thing, the account, project and app setup is unchanged, and how to get an X API key walks the current console flow.

One habit worth forming early: run playground start with the cost endpoints open in a second terminal while you build. Watching a number tick up per request changes how people write pagination loops, and it is a great deal cheaper than learning the same lesson from a bill.