# Bluesky Post Search

Searches public posts. version=v2 (default) takes query= and accepts sort=top or sort=recent; version=v1 takes q= and is the only generation that accepts the literal sort=latest token. Filter names differ per generation and mixing them is rejected rather than silently ignored. hits_total is an upstream estimate and saturates near 10000.

- **Documentation:** [https://scrappa.co/docs/bluesky-api/bluesky_search_posts](https://scrappa.co/docs/bluesky-api/bluesky_search_posts)
- **API group:** Bluesky API
- **Endpoint:** `GET https://scrappa.co/api/bluesky/search-posts`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | No | Search text for version=v2. |
| `q` | string | No | Search text for version=v1. |
| `version` | string | No | v2 (default) or v1. |
| `limit` | integer | No | Results per page, 1-100. |
| `sort` | string | No | V2: top or recent. V1: latest or top. |
| `cursor` | string | No | Opaque pagination cursor. |
| `authors[]` | array | No | Restrict to these authors. V2 only, plural key. |
| `hashtags[]` | array | No | Restrict to these hashtags. V2 only, plural key. |
| `domains[]` | array | No | Restrict to posts linking these domains. V2 only. |
| `hasMedia` | boolean | No | Only posts with media. V2 only. |
| `following` | boolean | No | Rejected with 422. This filter only narrows results for a viewer, and public Bluesky search is always read anonymously, so it could never do anything. |
| `author` | string | No | Restrict to one author. V1 only, singular key. |
| `tag[]` | array | No | Restrict to these hashtags. V1 only. This is the one plural filter on V1: repeat the key or pass a comma-separated list, and multiple tags are AND-matched. |
| `lang` | string | No | Restrict to this language code. V1 only. |
| `since` | string | No | Only posts after this timestamp. Both generations. |
| `until` | string | No | Only posts before this timestamp. Both generations. |
| `excludeAuthors[]` | array | No | Exclude these authors. V2 only, plural key. Accepted and forwarded; upstream effect unverified. |
| `excludeHashtags[]` | array | No | Exclude these hashtags. V2 only, plural key. Accepted and forwarded; upstream effect unverified. |
| `excludeMentions[]` | array | No | Exclude these mentions. V2 only, plural key. Accepted and forwarded; upstream effect unverified. |
| `excludeDomains[]` | array | No | Exclude posts linking these domains. V2 only. Accepted and forwarded; upstream effect unverified. |
| `excludeUrls[]` | array | No | Exclude posts linking these URLs. V2 only. Accepted and forwarded; upstream effect unverified. |
| `excludeLanguages[]` | array | No | Exclude these language codes. V2 only. Accepted and forwarded; upstream effect unverified. |
| `excludeEmbeddedAtUris[]` | array | No | Exclude posts embedding these records. V2 only. Accepted and forwarded; upstream effect unverified. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/bluesky/search-posts?query=bluesky&limit=10"
```

## Example response

```json
{
    "success": true,
    "hits_total": 10000,
    "hits_total_approximate": true,
    "detected_query_languages": [
        "en"
    ]
}
```

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)