# Twitter API 403 on a suspended search endpoint

## TL;DR
A 403 from the X API on search usually means the endpoint is restricted for your app's access tier or the app was suspended from that product, not that your request was malformed. Check the app's access level in the developer portal and the exact error code in the response body. If the tier does not include search, upgrade the product access or use a licensed social listening provider; there is no request tweak that unlocks a gated endpoint.

## The error
```text
HTTP 403 Forbidden
{"errors": [{"message": "This endpoint is not available for your access level."}]}
```

## When this helps
- X API search calls return 403
- a social listening pipeline loses search access
- evaluating X API tiers for a briefing agent
- migrating social search to a licensed provider

## When it doesn't
- the error is 401; that is credentials, not tier
- the error is 429; that is rate limit, not gating
- you want to scrape X instead; that violates the terms

## Works with
X API v2 as of 2026. Endpoint availability is tier-dependent and changes with X's pricing.

## Steps
### 1. Read the exact error code in the response body
```bash
curl -s "https://api.twitter.com/2/tweets/search/recent?query=[topic]" -H "your auth header -o search.json -w "HTTP %{http_code}\n"
python3 -c "import json; print(json.load(open("search.json")))"
```
Expected: The 403 body with the specific restriction message. Tier gating and suspension look different in the body; the fix depends on which it is.

### 2. Verify the app's access tier in the developer portal
```python
import requests, os
r = requests.get("https://api.twitter.com/2/usage/tweets", headers={"Authorization": "Bearer " + os.environ["X_BEARER"]}, timeout=20)
print(r.status_code)
```
Expected: A 200 on usage means the credentials are fine and the gate is product-tier, not auth. A 401 here means fix the credentials first.

### 3. Confirm the search product is in the current tier
```bash
printf 'X API tiers gate search differently: free and basic tiers exclude or limit\nsearch endpoints. Check the developer portal product list for the app and\nmatch the endpoint against the tier matrix before changing code.\n' | tee tier_check.txt
cat tier_check.txt
```
Expected: A written reminder of the tier check. Most 403s on search resolve to a tier answer, not a code answer.

### 4. Route social search to a licensed provider if the tier excludes it
```python
import json
routing = {"social_search": "licensed social listening provider", "account_lookup": "x api basic tier"}
open("social_routing.json", "w").write(json.dumps(routing, indent=2))
print("search routed to licensed provider")
```
Expected: A routing table. Licensed providers carry X data with proper rights when the API tier does not include search.

## Other ways people phrase this
### twitter api 403 search endpoint
Tier gating is the usual cause. Check the product access before debugging the request.

### x api endpoint not available access level
The body message for tier gating. Match the endpoint to the tier matrix.

### twitter search api suspended
Suspension shows differently in the body. Appeal through the developer portal; do not work around it.

## Why it happens
X gates API products by paid tier, and search endpoints sit in the higher tiers. A 403 on search is the tier enforcement, telling you the app's product does not include that endpoint. No parameter or header changes the tier; only the product subscription or a different data source does.

## Edge cases
- Tier changes can take time to propagate to all endpoints; wait before retesting.
- Posting and search are separate products; one working does not imply the other.
- Licensed providers have their own rate limits; size the polling to them.
- Keep the X app in good standing; tier violations can lead to suspension.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_CF9teodywKnN1JKBZG9xvQ