> For the complete documentation index, see [llms.txt](https://docs.simkl.org/how-to-use-simkl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.simkl.org/how-to-use-simkl/advanced-usage/additional-tools/x-twitter-sharing.md).
# X (Twitter) sharing
Post to X automatically when you watch an episode or movie, rate a title, and every Monday with your weekly stats.
X no longer gives apps like Simkl free access to post for their users, so Simkl connects to X through your own X developer app. X bills you directly for the posts your app makes, from prepaid credits. Simkl doesn't charge anything for X sharing.
Setup takes about 10 minutes. You'll need your X account and a credit or debit card for X credits.
### What X charges
X uses pay-per-use pricing: no subscription, you buy credits and each post uses some of them. Every Simkl post includes a link to the title on Simkl, so X bills it at the rate for posts with a link.
| Item | Price |
| --------------------------------------------------------- | ------------------- |
| Each Simkl post (contains a link) | $0.20 |
| Example: 40 episodes a month plus weekly stats (44 posts) | about $8.80 / month |
| Smallest credit pack in the console | $5 |
{% hint style="info" %}
**Free credits and limits**
* X matches your first credit purchase with up to $20 in free credits. Prepaid cards don't qualify.
* If you turn on auto-recharge, X matches your first automatic top-up with up to $50 in free credits.
* Free credits expire 3 months after X grants them. Credits you buy don't expire.
* To stay in control, set a **Billing Cycle Cap** under Billing → Credits → Manage Spend Cap. When you reach it, X stops posting until the next billing cycle.
* Prices shown are from October 2026. X can change them; current rates are on X's [pricing page](https://docs.x.com/x-api/getting-started/pricing).
{% endhint %}
Older developer accounts may still show a legacy Free plan. X closed it to new sign-ups in February 2026, so new accounts start on Pay Per Use.
### Step 1: Sign in to the X Developer Console
Go to [console.x.com](https://console.x.com) and sign in with the X account you want Simkl to post to.
The first time, X asks you to accept its Developer Agreement and Policy and to describe how you'll use the API. You can write something like:
{% hint style="success" %}
I will use the X API to post my own TV show, anime and movie watch activity from Simkl to my own X account.
{% endhint %}
### Step 2: Add credits
In the left menu open **Billing → Credits** and click **Purchase credits**.
Pick an amount and click **Continue to payment**. $5 covers about 25 Simkl posts.
### Step 3: Create an app
Open **Apps** in the left menu and click **Create App**.
* **Application Name:** anything you like, for example `Simkl Sharing`. If X says the name is taken, add your username to it.
* **Project Access:** keep your project ticked. It shows **Pay Per Use**. You can leave the environment as it is.
Click **Create**. If X shows you keys straight away, you can close that window; you'll copy the ones Simkl needs in step 5.
### Step 4: Set up user authentication
On your app's page, click **Settings**.
Fill in the Authentication settings:
| Setting | Value |
| --------------------------- | -------------------------------------------------------------------------------------------- |
| App permissions | **Read and write** |
| Type of App | **Web App, Automated App or Bot** |
| Callback URI / Redirect URL | The URL below |
| Website URL | Your own website or your X profile, like `https://x.com/your_username`. Don't use simkl.com. |
Callback URI / Redirect URL:
```
https://passport.simkl.com/?do=tw_pub
```
Leave the other fields empty and click **Save Changes**.
### Step 5: Copy your Client ID and Client Secret
Click **Back to Keys**. Under **OAuth 2.0 Keys**, copy the **Client ID** and the **Client Secret** and keep them somewhere safe.
* Use the OAuth 2.0 keys. The OAuth 1.0 Consumer Key won't work with Simkl.
* If the Client Secret is hidden and you didn't save it, click **Regenerate** to get a new one.
* Treat the Client Secret like a password and don't share it.
### Step 6: Connect X on Simkl
On Simkl, go to [Settings → Sharing](https://simkl.com/settings/sharing/). Paste your Client ID and Client Secret and click **Connect X**.
### Step 7: Authorize your app on X
X opens a page asking you to authorize your new app. Check that the account shown is the one you want Simkl to post to, tick **I trust this app**, then click **Authorize app**.
X will take you back to Simkl, and the Sharing page will show **Connected**.
### Step 8: Choose what to share
Back on Settings → Sharing, pick what Simkl posts:
* **#JustWatched** when you mark an episode or movie as watched, or when Simkl scrobbles it
* **Weekly stats** every Monday
* **#JustRated** when you rate a movie, show or anime
All three are switched on the first time you connect. Untick any you don't want; each post costs credits. Under **Post text**, click Edit next to a post to change its words. Click a variable like %SHOW\_NAME% to add it, then click Save Changes.
{% hint style="success" %}
**You're done.** Simkl now posts to your X profile a few minutes after you watch or rate something.
{% endhint %}
### Troubleshooting
**"Enter both your Client ID and Client Secret"**
One of the two fields is empty. Paste both values from step 5.
**"X didn't accept these keys"**
The Client Secret is wrong or cut short. Copy it again, or click Regenerate in the Developer Console and paste the new one. Turn off ad blockers for simkl.com and x.com while you connect.
**X shows an error instead of the authorize page**
Check step 4. The Callback URI must be exactly `https://passport.simkl.com/?do=tw_pub` and Type of App must be Web App, Automated App or Bot.
**Posts stopped appearing**
You've probably run out of credits or hit your spend cap. Check Billing → Credits. If X rejects posts, Simkl may disconnect X; add credits and connect again on Settings → Sharing.
### Your account stays in your control
* Simkl stores your Client ID and Client Secret encrypted and uses them only to post the activity you switched on.
* Simkl never sees your X password or your direct messages.
* To stop sharing, open Settings → Sharing on Simkl and click **Disconnect**. You can also remove the app on X under Settings and privacy → Security and account access → Apps and sessions, or delete the app in the Developer Console.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.simkl.org/how-to-use-simkl/advanced-usage/additional-tools/x-twitter-sharing.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
