> For the complete documentation index, see [llms.txt](https://docs.posynt.win/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.posynt.win/api-reference/tracks.md).

# Tracked hashtags

A "track" = a hashtag Posynt watches for you. A track for `ledroplive` matches both the hashtag form (`#ledroplive`) and the cashtag form (`$ledroplive`) — useful for tickers, since people write `$OG` as often as `#OG`. You don't need separate tracks for each form.

## List hashtags

```bash
curl https://api.posynt.win/v1/tracks \
  -H "Authorization: Bearer psy_live_xxx"
```

```json
{
  "data": [
    { "id": "trk_9f2a", "hashtag": "ledroplive", "lang": null, "exclude_retweets": true, "track_engagement": false, "track_likes": true, "track_reposts": true, "track_comments": true, "status": "active", "created_at": "2026-07-11T10:00:00Z" }
  ]
}
```

## Add a hashtag

```bash
curl -X POST https://api.posynt.win/v1/tracks \
  -H "Authorization: Bearer psy_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"hashtag": "ledroplive", "lang": "en"}'
```

### Parameters

| Field              | Type   | Required | Description                                                                                  |
| ------------------ | ------ | -------- | -------------------------------------------------------------------------------------------- |
| `hashtag`          | string | ✅        | The hashtag without the `#`. Matches the `$cashtag` form too — see above.                    |
| `lang`             | string | –        | Language filter (e.g. `en`, `fr`).                                                           |
| `exclude_retweets` | bool   | –        | Ignore retweets (default `true`).                                                            |
| `track_engagement` | bool   | –        | Also watch RT/like/comment counts + who, on every matched post (default `false`). See below. |
| `track_likes`      | bool   | –        | Track likes (default `true`). Only matters while `track_engagement` is on.                   |
| `track_reposts`    | bool   | –        | Track retweets/reposts (default `true`). Only matters while `track_engagement` is on.        |
| `track_comments`   | bool   | –        | Track replies (default `true`). Only matters while `track_engagement` is on.                 |

{% hint style="info" %}
The number of active hashtags is capped by your plan. A `POST` beyond the limit returns `403` with the code `plan_limit_reached`.
{% endhint %}

## Engagement tracking

Turning `track_engagement` on for a hashtag means every post it matches also gets polled for its **real RT/like/comment counts** plus a capped sample of which accounts retweeted/liked/replied. This shows up on the post via `GET /v1/posts` as an `engagement` object, and — if you flip the matching option on a notification channel — fires an extra alert per new retweet/like/comment (see [Notifications](/guides/notifications.md)).

The number of hashtags **and** accounts with engagement tracking on, combined, is capped by your plan (`engagement_limit` on `GET /v1/me`) — a `POST`/`PATCH` that would exceed it returns `403` with `plan_limit_reached`.

Toggle it after creation:

```bash
curl -X PATCH https://api.posynt.win/v1/tracks/trk_9f2a \
  -H "Authorization: Bearer psy_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"track_engagement": true}'
```

By default that tracks all three of likes, reposts and comments. Track only some of them by turning the others off — same `PATCH`, any subset:

```bash
curl -X PATCH https://api.posynt.win/v1/tracks/trk_9f2a \
  -H "Authorization: Bearer psy_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"track_likes": false, "track_comments": false}'
```

That example leaves only reposts tracked — `retweet_count`/`retweeters` keep updating and firing new-repost alerts, while `like_count`/`likers` and `reply_count`/`repliers` just stop being refreshed (they hold whatever value they last had, typically the defaults if reposts-only was set from the start).

Polling stops 48h after a post is detected, and the RT/like/comment *lists* are a capped sample, not exhaustive — X doesn't expose full pagination cheaply. The *counts* are always the tweet's real totals, though.

The `engagement` object on a post from `GET /v1/posts`:

```json
{
  "retweet_count": 128,
  "like_count": 941,
  "reply_count": 37,
  "retweeters": ["@0xwhale", "@cryptofrog", "..."],
  "likers": ["@0xwhale", "@nftguy", "..."],
  "repliers": ["@0xwhale", "..."],
  "updated_at": "2026-08-25T01:40:00Z"
}
```

## Delete a hashtag

```bash
curl -X DELETE https://api.posynt.win/v1/tracks/trk_9f2a \
  -H "Authorization: Bearer psy_live_xxx"
```

```json
{ "id": "trk_9f2a", "deleted": true }
```


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.posynt.win/api-reference/tracks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.