---
title: Search X
description: Find posts and people with the same five feeds as X search.
sidebar:
  order: 2
  icon: search
---

## Search for posts

`GET /search?q={query}` — the permalink form, mirroring `x.com/search`.

```bash
curl -sS -G 'https://x.pcstyle.dev/search' \
  --data-urlencode 'q=from:vercel release' \
  --data-urlencode 'feed=latest' \
  --data-urlencode 'limit=20'
```

`GET /api/v1/search?q={query}` — the same search on the [versioned surface](/versioning). Same parameters, same body.

```bash
curl -sS -G 'https://x.pcstyle.dev/api/v1/search' \
  --data-urlencode 'q=from:vercel release' \
  --data-urlencode 'format=json'
```

Use `--data-urlencode` for spaces, hashtags, and query operators. The query is passed to the search provider.

## Choose a feed

| `feed` | Results |
| --- | --- |
| `latest` | Recent matching posts. Default. |
| `top` | Top matching posts. |
| `photos` | Matching posts with photos. |
| `videos` | Matching posts with videos. |
| `users` | Matching account profiles. |

Feed names are case-insensitive. `media` is an alias for `photos`; unknown values fall back to `latest`.

**Photos**

```bash
curl -sS 'https://x.pcstyle.dev/search?q=architecture&feed=photos'
```

**Videos**

```bash
curl -sS 'https://x.pcstyle.dev/search?q=animation&feed=videos'
```

**Users**

```bash
curl -sS 'https://x.pcstyle.dev/search?q=typescript&feed=users&full=true'
```

## Parameters

| Parameter | Default | Behavior |
| --- | --- | --- |
| `q` | Required | Nonempty search query. |
| `feed` | `latest` | One of the five feeds above. |
| `limit` | `20` | Results per response, maximum **20**. Larger values are clamped. |
| `cursor` | — | Opaque `nextCursor` from the previous response. |
| `page` | `1` | Page 1–10; prefer cursors for continuation. |
| `full` | `false` | `true` adds dates and metrics, or profile details for Users. |
| `format` | `markdown` | `markdown` or `json`. |
| `nocache` | `false` | `true` bypasses the application cache. |

Browse boolean parameters also accept `1`. [Pagination examples](/pagination).

## Read user results in JSON

Post feeds return a `posts` array. The Users feed returns a `users` array instead.

```js
const response = await fetch(
  'https://x.pcstyle.dev/search?q=typescript&feed=users&format=json'
)
if (!response.ok) throw new Error(`Search failed: ${response.status}`)
const { users, nextCursor } = await response.json()
for (const user of users) console.log(user.screen_name, user.name)
```

## Availability and limits

Search is the one route with a tight allowance: **5 uncached requests per minute per IP** (`search-ip`), plus **10 account-backed lookups per IP per 15-minute window** (`account-ip`) for Photos, Videos, Users, and the Latest/Top live fallback. Cache hits are free. Each page of a numbered page walk counts as one request; a cursor costs one.

Every response reports what is left in its `RateLimit` headers, so a client can pace itself rather than discover the limit:

```http
RateLimit: "api-ip";r=599;t=60, "search-ip";r=5;t=60, "account-ip";r=10;t=900
RateLimit-Remaining: 5
```

A rejected request is `429` with `Retry-After` in seconds and a `rate_limited` problem document. [Full limit and header reference](/reliability#rate-limits).

:::warning
When live search is unavailable, Latest and Top may return web-indexed snippets. These responses include `X-Search-Degraded: true` and a note in the Markdown. Their ordering, coverage, and text can differ from live results, and they do not paginate.

Photos, Videos, and Users return `503` when their live source is unavailable. They never substitute unfiltered web snippets.
:::

See [errors, limits, and caching](/reliability) and the [error catalogue](/errors).