POST /v2/social/profiles/searches/smart

The smart search endpoint accepts a plain English query and returns a ranked list of matching profiles. Orbit resolves your query through structured, semantic, and agentic search modes automatically — you don’t need to specify a mode. Each successful request costs credits; requests that return no results or fail validation are refunded.

Authentication

Include your developer API key in every request. The key must have the search:read scope.

Authorization: Bearer sk_orb_...

Request

POST /v2/social/profiles/searches/smart

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer sk_orb_...` with `search:read` scope
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	A UUID or client-generated key for safe retries

Always send an Idempotency-Key header. If you omit it, the server uses the request ID, which prevents duplicate charges within a single request but cannot deduplicate a client-side retry. Use a fresh idempotency key for every new request attempt.

Body parameters

query

string

required

Natural language description of the people you’re searching for. Cannot be empty.Example: "founders in sf", "machine learning engineers at Series B startups"

numUsers

number

required

Number of results to return. Must be a positive integer. Maximum value is 100.

searchScope

object

Scope of the search. Omit this field or set {"type":"global"} to search the full Orbit index. Use a directory-scoped value to restrict results to one or more directories.

Show properties

searchScope.type

string

required

One of: "global", "directory", "directories"

searchScope.directoryId

string

Required when type is "directory". The UUID of a single directory to search.

searchScope.directoryIds

string[]

Required when type is "directories". An array of directory UUIDs to search. All directories must belong to the same organization.

userId is not accepted in the request body.
searchId (search replay) is not accepted in the request body.
Personal API keys can only use global search. To use a directory scope, you must use an organization API key.

Search scope examples

Global
Single directory
Multiple directories

Omit searchScope entirely, or pass {"type":"global"}, to search the full Orbit index.

{
  "query": "founders in sf",
  "numUsers": 10
}

Search within one directory. Requires an organization API key with a directory search grant.

{
  "query": "festival programmers",
  "numUsers": 10,
  "searchScope": {
    "type": "directory",
    "directoryId": "DIRECTORY_UUID"
  }
}

Search across several directories in a single request. All directories must belong to the same organization. Requires an organization API key.

{
  "query": "festival programmers",
  "numUsers": 10,
  "searchScope": {
    "type": "directories",
    "directoryIds": ["DIRECTORY_UUID_A", "DIRECTORY_UUID_B"]
  }
}

Response

200 Success

{
  "status": "success",
  "searchId": "uuid",
  "payload": {
    "users": []
  }
}

status

string

required

Always "success" for a 200 response.

searchId

string

required

Unique identifier for this search request. Useful for support and debugging.

payload

object

required

Hide properties

payload.users

object[]

required

Array of matched profile objects, ranked by relevance. Each object includes at minimum a userId field you can pass to the Profile Read endpoint. The array is empty when no profiles matched.

Response headers

Header	Description
`X-Developer-API-Credits-Remaining`	Your remaining credit balance after this request was charged

Credits

Each successful smart search costs 2 credits by default, regardless of numUsers. Credits are reserved before the search runs, so out-of-credit requests fail immediately without consuming search resources. If a search returns no results or fails, the reservation is refunded.

Rate limits

60 requests per 60 seconds per API key. Rate limits are tracked per key, not per IP address. A 429 response does not consume credits.

Error responses

400 — Bad request

Code	Description
`developer_query_required`	`query` is missing or empty
`developer_num_users_required`	`numUsers` is missing or not a valid positive integer
`developer_num_users_limit_exceeded`	`numUsers` exceeds the maximum of 100
`developer_user_id_override_forbidden`	Request body includes a `userId` field, which is not permitted
`developer_search_replay_unsupported`	Request body includes a `searchId` field; search replay is not supported for developer API keys

401 — Unauthorized

Code	Description
`missing_api_key`	No `Authorization: Bearer sk_orb_...` header was provided

402 — Payment required

Code	Description
`developer_api_credits_insufficient`	Your remaining credits are lower than the cost of this search

403 — Forbidden

Code	Description
`invalid_api_key`	The key is malformed, revoked, expired, or unknown
`missing_api_key_scope`	The key does not have the `search:read` scope
`developer_api_key_organization_required`	A directory scope was requested, but the key is a personal API key
`developer_api_key_organization_forbidden`	The organization API key is not authorized for the requested organization search scope
`search_directory_access_api_key_forbidden`	The organization API key does not have a matching directory search grant

404 — Not found

Code	Description
`search_directory_not_found`	One or more requested directories do not exist, are archived, or are unavailable for search. Also returned when a search runs successfully but no profiles matched — in this case, no credits are consumed.

409 — Conflict

Code	Description
`developer_api_idempotency_key_conflict`	The idempotency key was reused with different request parameters. Use a different key.
`developer_api_idempotency_key_refunded`	The idempotency key belongs to a previously refunded request. Send a fresh idempotency key to retry.

429 — Rate limited

Code	Description
`developer_api_key_rate_limited`	You have exceeded 60 requests per 60 seconds for this API key

Code examples

curl -X POST "$API_BASE/v2/social/profiles/searches/smart" \
  -H "Authorization: Bearer sk_orb_REDACTED" \
  -H "Idempotency-Key: request-uuid-or-client-retry-key" \
  -H "Content-Type: application/json" \
  -d '{"query":"founders in sf","numUsers":10}'

Search

Keys

Directories

Organizations

POST /v2/social/profiles/searches/smart — search

Authentication

Request

Headers

Body parameters

Search scope examples

Response

200 Success

Response headers

Credits

Rate limits

Error responses

Code examples

Search

Keys

Directories

Organizations

Documentation Index

​Authentication

​Request

​Headers

​Body parameters

​Search scope examples

​Response

​200 Success

​Response headers

​Credits

​Rate limits

​Error responses

​Code examples

Authentication

Request

Headers

Body parameters

Search scope examples

Response

200 Success

Response headers

Credits

Rate limits

Error responses

Code examples