Join an X Community API | Twitter Community Join

Join Community makes your own X account a member of an open X Community. Pass the numeric community_id; the call runs as your registered X session (or auth_token and ct0 sent with the call) and answers status joined on success. Communities that require moderator approval are refused with a 409 and nothing is submitted. One $0.0008 write, billed only when the join applies.

curl -X POST "https://example.com/community/join?community_id=1493446837214187523" \  -H "Content-Type: application/json" \  -d '{    "community_id": "1493446837214187523"  }'

{  "ok": true,  "action": "community_join",  "community_id": "1493446837214187523",  "status": "joined",  "community": null}

{  "error": "bad_request",  "message": "`community_id` must be a numeric X community id, e.g. 1493446837214187523 (the digits in x.com/i/communities/<id>)."}

{  "error": "session_dead",  "message": "Your registered Twitter session is no longer valid. Re-register via POST /twitter/customer/session."}

{  "error": "insufficient_credits",  "message": "Your balance is exhausted. Top up your credits to continue."}

{  "ok": false,  "action": "community_join",  "community_id": "1493446837214187523",  "status": null,  "error": "account_suspended",  "message": "X reports the linked account is suspended (X code 64). No write can succeed until that is resolved in the X app. A registered session has been marked dead and must be re-registered.",  "community": null}

{  "ok": false,  "action": "community_join",  "community_id": "1493446837214187523",  "status": null,  "error": "community_not_found",  "message": "No community exists with this id, or it is not available to the linked account.",  "community": null}

{  "ok": false,  "action": "community_join",  "community_id": "1493446837214187523",  "status": null,  "error": "join_requires_approval",  "message": "This community requires moderator approval to join. Approval-gated communities are not supported yet: this endpoint joins open communities only and did not submit a join request. Check join_policy with GET /twitter/community/info first.",  "community": null}

{  "ok": false,  "action": "community_join",  "community_id": "1493446837214187523",  "status": null,  "error": "write_not_applied",  "message": "X did not apply this change. See `reason` for X's own classification.",  "community": null,  "reason": "upstream_error"}

{  "error": "rate_limited",  "message": "Upstream throttled or blocked this request. Retry shortly.",  "reason": "rate_limited"}

{  "error": "error",  "message": "Upstream request failed.",  "reason": "upstream_error"}

Pricing

One $0.0008 write, and you are not charged when the join does not apply. Every non-200 answer, including the 409 for an approval-gated community, is free.

When to use

Use it to add your account to a community programmatically, for example joining every open community a Community Search turns up for your niche. Check join_policy with Community Info first: this endpoint joins open communities only.

Notes

• OPEN COMMUNITIES ONLY. A community whose join_policy requires moderator approval answers 409 join_requires_approval, and no join request is sent for you. Read join_policy from Community Info before calling.
• Other 409 answers: already_member when the account is already in the community, and session_required when the key has no registered session and none was sent with the call. Other 403 answers: account_locked (X code 326), and forbidden when X refuses the action for the account.
• Every non-200 answer is free. A 200 whose upstream answer carried an error is never reported as a success.
• The error bodies for join_requires_approval, already_member, community_not_found and account_suspended or account_locked carry the same layout as the 200 (ok, action, community_id, status, community) plus error and message, and may also carry a machine-readable reason.

Related endpoints

• Leave Community: Leave an X Community as your own account.
• Community Info: Metadata, rules and banners for one X Community.
• Community Search: Search X Communities by keyword.
• Community Memberships: List every community a given account belongs to.

FAQ

Does this need my own X session?

Yes. Joining changes which account is a member, so it runs as the account you registered with POST /customer/session, or as the auth_token and ct0 you send with the call (x-auth-token and x-ct0 headers, or JSON body fields).

Can it join a community that requires approval?

Not yet. A community whose join_policy requires moderator approval answers 409 join_requires_approval, and no join request is sent on your behalf. Read join_policy from Community Info before calling.

What if the account is already a member?

You get a 409 already_member, nothing changes, and you are not billed.

What does the community field contain?

Only the keys X returned with the join, among id, name, member_count, role and join_policy. It is null when X returned no community object, and no field is filled with a default. Call Community Info for the full record.