# tech.waow.typeahead.searchActors

> Published by [typeahead.waow.tech](https://lexicon.garden/identity/did:plc:y6kywgnb7xletjpa5hhxmd4k)

✓ This is the authoritative definition for this NSID.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:y6kywgnb7xletjpa5hhxmd4k/tech.waow.typeahead.searchActors)
- [Documentation](https://lexicon.garden/lexicon/did:plc:y6kywgnb7xletjpa5hhxmd4k/tech.waow.typeahead.searchActors/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:y6kywgnb7xletjpa5hhxmd4k/tech.waow.typeahead.searchActors/examples)

## Definitions

### `tech.waow.typeahead.searchActors`

**Type**: `query`

Prefix search for atproto actors, ordered for typeahead use. Served entirely from a community-run index (https://typeahead.waow.tech); unauthenticated, CORS-enabled, results edge-cached for 60s. Also served at app.bsky.actor.searchActorsTypeahead as a drop-in migration alias with an identical response.

#### Parameters

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `q` | `string` | Yes | Search prefix; matched case-insensitively against handles and display names (CJK display names are matched via bigrams). |
| `limit` | `integer` | No | Maximum number of actors to return. |

#### Output

**Encoding**: `application/json`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `actors` | `array` | Yes | Matching actors, best match first. Ranking blends prefix quality with a stored popularity score; actors hidden by moderation are excluded. |

### `tech.waow.typeahead.searchActors#actorBasic`

**Type**: `object`

Basic actor profile. Matches the shape of app.bsky.actor.defs#profileViewBasic minus the authenticated viewer state, so results are interchangeable with bluesky's for unauthenticated use.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `did` | `string` (did) | Yes | The actor's decentralized identifier. |
| `avatar` | `string` (uri) | No | Avatar image URL — usually a bluesky CDN URL, but may point directly at the actor's PDS blob endpoint for accounts bluesky's CDN no longer serves. |
| `handle` | `string` (handle) | Yes | The actor's current handle, e.g. zzstoatzz.io. |
| `labels` | `unknown` | No | Pass-through of the actor's com.atproto.label.defs#label array (self-labels and moderation-service labels) as last seen; may be empty. |
| `createdAt` | `string` (datetime) | No | Account creation time as reported by the actor's profile view; absent if unknown. |
| `associated` | `unknown` | No | Pass-through of app.bsky.actor.defs#profileAssociated as last seen from the actor's profile (lists, feedgens, starter packs, chat settings); absent if never observed. |
| `displayName` | `string` | No | Self-declared display name from the actor's profile record; absent if unset. |

## Examples

The following examples demonstrate valid data for this lexicon. [View all examples](https://lexicon.garden/lexicon/did:plc:y6kywgnb7xletjpa5hhxmd4k/tech.waow.typeahead.searchActors/examples)

### Example 1 (`#actorBasic`)

**Description**: Actor with every optional field populated, including a self-label and a PDS-direct avatar URL (used when bluesky's CDN no longer serves the account).

```json
{
  "did": "did:plc:65sucjiel52gefhcdcypynsr",
  "avatar": "https://cdn.bsky.app/img/avatar/plain/did:plc:65sucjiel52gefhcdcypynsr/bafkreigipzdpd2gx7otqdlhtcdom45ol7esfe25any5vqrk7kdtmohi2ae",
  "handle": "phi.zzstoatzz.io",
  "labels": [
    {
      "cid": "bafyreidvy4hbd46alju5uxh6h7kc7av3l6rzofut3xg7nf3jr7k6ntrhdm",
      "cts": "1970-01-01T00:00:00.000Z",
      "src": "did:plc:65sucjiel52gefhcdcypynsr",
      "uri": "at://did:plc:65sucjiel52gefhcdcypynsr/app.bsky.actor.profile/self",
      "val": "bot"
    }
  ],
  "createdAt": "2025-03-17T06:18:35.045Z",
  "associated": {
    "feedgens": 2,
    "activitySubscription": {
      "allowSubscriptions": "followers"
    }
  },
  "displayName": "ϕ"
}
```

### Example 2 (`#actorBasic`)

**Description**: Minimal actor — only the required fields. Typical of an account discovered via the firehose that has never written a profile record: no display name, avatar, or aggregates yet.

```json
{
  "did": "did:plc:ewvi7nxzyoun6zhxrhs64oiz",
  "handle": "atproto.com"
}
```

### Example 3 (`#main`)

**Description**: Full response for GET /xrpc/tech.waow.typeahead.searchActors?q=zzstoatzz&limit=2 — exact-handle match ranked first, then other prefix matches.

```json
{
  "actors": [
    {
      "did": "did:plc:xbtmt2zjwlrfegqvch7fboei",
      "avatar": "https://pds.zzstoatzz.io/xrpc/com.atproto.sync.getBlob?did=did:plc:xbtmt2zjwlrfegqvch7fboei&cid=bafkreidsppzvcystsy2g3m6rut2zyuvdzsyjvm2m2stjjxydfy7jfv2v54",
      "handle": "zzstoatzz.io",
      "labels": [],
      "createdAt": "2024-10-17T22:23:42.606Z",
      "associated": {
        "chat": {
          "allowIncoming": "all",
          "allowGroupInvites": "all"
        },
        "lists": 4,
        "feedgens": 3,
        "starterPacks": 3,
        "activitySubscription": {
          "allowSubscriptions": "followers"
        }
      },
      "displayName": "nate"
    },
    {
      "did": "did:plc:65sucjiel52gefhcdcypynsr",
      "avatar": "https://cdn.bsky.app/img/avatar/plain/did:plc:65sucjiel52gefhcdcypynsr/bafkreigipzdpd2gx7otqdlhtcdom45ol7esfe25any5vqrk7kdtmohi2ae",
      "handle": "phi.zzstoatzz.io",
      "labels": [
        {
          "cid": "bafyreidvy4hbd46alju5uxh6h7kc7av3l6rzofut3xg7nf3jr7k6ntrhdm",
          "cts": "1970-01-01T00:00:00.000Z",
          "src": "did:plc:65sucjiel52gefhcdcypynsr",
          "uri": "at://did:plc:65sucjiel52gefhcdcypynsr/app.bsky.actor.profile/self",
          "val": "bot"
        }
      ],
      "createdAt": "2025-03-17T06:18:35.045Z",
      "associated": {
        "feedgens": 2,
        "activitySubscription": {
          "allowSubscriptions": "followers"
        }
      },
      "displayName": "ϕ"
    }
  ]
}
```

## Raw Schema

```json
{
  "id": "tech.waow.typeahead.searchActors",
  "defs": {
    "main": {
      "type": "query",
      "output": {
        "schema": {
          "type": "object",
          "required": [
            "actors"
          ],
          "properties": {
            "actors": {
              "type": "array",
              "items": {
                "ref": "#actorBasic",
                "type": "ref"
              },
              "description": "Matching actors, best match first. Ranking blends prefix quality with a stored popularity score; actors hidden by moderation are excluded."
            }
          }
        },
        "encoding": "application/json"
      },
      "parameters": {
        "type": "params",
        "required": [
          "q"
        ],
        "properties": {
          "q": {
            "type": "string",
            "description": "Search prefix; matched case-insensitively against handles and display names (CJK display names are matched via bigrams)."
          },
          "limit": {
            "type": "integer",
            "default": 10,
            "maximum": 100,
            "minimum": 1,
            "description": "Maximum number of actors to return."
          }
        }
      },
      "description": "Prefix search for atproto actors, ordered for typeahead use. Served entirely from a community-run index (https://typeahead.waow.tech); unauthenticated, CORS-enabled, results edge-cached for 60s. Also served at app.bsky.actor.searchActorsTypeahead as a drop-in migration alias with an identical response."
    },
    "actorBasic": {
      "type": "object",
      "required": [
        "did",
        "handle"
      ],
      "properties": {
        "did": {
          "type": "string",
          "format": "did",
          "description": "The actor's decentralized identifier."
        },
        "avatar": {
          "type": "string",
          "format": "uri",
          "description": "Avatar image URL — usually a bluesky CDN URL, but may point directly at the actor's PDS blob endpoint for accounts bluesky's CDN no longer serves."
        },
        "handle": {
          "type": "string",
          "format": "handle",
          "description": "The actor's current handle, e.g. zzstoatzz.io."
        },
        "labels": {
          "type": "unknown",
          "description": "Pass-through of the actor's com.atproto.label.defs#label array (self-labels and moderation-service labels) as last seen; may be empty."
        },
        "createdAt": {
          "type": "string",
          "format": "datetime",
          "description": "Account creation time as reported by the actor's profile view; absent if unknown."
        },
        "associated": {
          "type": "unknown",
          "description": "Pass-through of app.bsky.actor.defs#profileAssociated as last seen from the actor's profile (lists, feedgens, starter packs, chat settings); absent if never observed."
        },
        "displayName": {
          "type": "string",
          "maxLength": 640,
          "description": "Self-declared display name from the actor's profile record; absent if unset.",
          "maxGraphemes": 64
        }
      },
      "description": "Basic actor profile. Matches the shape of app.bsky.actor.defs#profileViewBasic minus the authenticated viewer state, so results are interchangeable with bluesky's for unauthenticated use."
    }
  },
  "$type": "com.atproto.lexicon.schema",
  "lexicon": 1
}
```