# Query contacts

Make a read-only request and paginate through matching contacts.

Use the query endpoint to select contact properties, filter records, and read
additional pages. This guide uses `curl` so it does not assume an SDK method.

## Prerequisites

You need:

- a Micro API key from Micro settings;
- the UUID of a disposable workspace you can access; and
- permission to read contacts in that workspace.

Keep the key in an environment variable and do not commit it. The public API host
is `https://developers.micro.so`; `api.micro.so` is the app backend and does not
accept this API-key flow.

```bash
export MICRO_API_KEY="replace-with-your-api-key"
export MICRO_TEAM_ID="00000000-0000-4000-8000-000000000000"
```

## Send the request

This request returns at most 10 contacts and selects only `full_name` and
`email`. It does not change workspace data.

```bash
curl --request POST \
  "https://developers.micro.so/v2/prism/${MICRO_TEAM_ID}/contact/query" \
  --header "content-type: application/json" \
  --header "x-api-key: ${MICRO_API_KEY}" \
  --data '{
    "query": {
      "select": ["full_name", "email"],
      "limit": 10
    }
  }'
```

A successful response has this shape. `id` is always returned at the top level,
even when it is not included in `select`.

```json
{
  "data": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "properties": {
        "full_name": "Sarah Chen",
        "email": "sarah@example.com"
      },
      "is_user_object": false
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## Read the next page

When `has_more` is `true`, pass `next_cursor` back unchanged as
`query.cursor`. Do not parse it. The current cursor is offset-based and can drift
when records are added or removed during a multi-page read.

```bash
curl --request POST \
  "https://developers.micro.so/v2/prism/${MICRO_TEAM_ID}/contact/query" \
  --header "content-type: application/json" \
  --header "x-api-key: ${MICRO_API_KEY}" \
  --data '{
    "query": {
      "select": ["full_name", "email"],
      "cursor": "replace-with-next-cursor"
    }
  }'
```

Stop when `has_more` is `false`. `next_cursor` is then `null`. The maximum page
size is 50; larger limits are rejected.

## Recover from errors

- `400`: check the object type, selected property slugs, filters, and page limit.
- `401`: make sure `x-api-key` is present and the key is valid.
- `403`: check the API key and confirm it can access this workspace.
- `500`: retry with backoff. Include the response's `x-request-id` if you contact
  support.

See the [query endpoint reference](/docs/api-reference/query-records) for all
request fields, response schemas, and error definitions included in this pilot.