---
title: "Queue an owner-approved phone query. Poll the Location URL for the actual result."
method: POST
path: "/api/v1/queries"
---

# Queue an owner-approved phone query. Poll the Location URL for the actual result.

`POST /api/v1/queries`

## Request

- Base URL: `https://myself.md`
- URL: `https://myself.md/api/v1/queries`
- Auth: HTTP bearer

Idempotency keys are scoped to account and agent client. Identical live retries reuse the job without another billing reservation. Changed arguments, unavailable originals and revoked grants fail. Jobs expire after five minutes; activity fingerprints are retained for 90 days. A 202 response does not prove completion.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `deviceId` string, uuid, required: Owned phone UUID returned by list_connected_phones. Use get_phone_data_catalog to check its current connectivity and grants.
  - `profileId` string, required: Stable profile ID returned by get_phone_data_catalog. Resolve user-provided names from catalog.profiles first; ask when names are ambiguous. Query access requires the relevant individual data permission.
  - `domain` 'health' | 'time' | 'location', required: Data domain from get_phone_data_catalog. The chosen profile and phone-wide grant must both permit it.
  - `type` string, required: Exact native type identifier from the selected catalog domain, without the native: prefix. Do not invent type names.
  - `source` 'native': Phone capture adapter; native includes OS APIs and explicitly selected WHOOP types under separate provider consent. Returned records identify the actual source.
  - `start` string, date-time, required: Inclusive start of the query interval as a UTC ISO 8601 timestamp. The positive interval must be at most 31 days.
  - `end` string, date-time, required: End of the query interval as a UTC ISO 8601 timestamp, later than start and no more than 31 days after it.
  - `cursor` string: Pagination cursor returned by the preceding response. Omit for the first page; preserve the other query arguments when continuing.
  - `limit` integer: Maximum records in this page, up to 50. Follow the returned nextCursor to continue.
  - `format` 'json' | 'jsonl': Response serialization format; JSON returns structured records and JSONL returns one serialized record per line.
  - `schema` 'myself.md.export.v1': Export schema version from list_export_schemas; omit to use the released default version.

## Response `202`

Query accepted, or original live query returned.

- object
  - `requestId` string, uuid, required
  - `status` 'queued' | 'running' | 'complete' | 'failed', required
  - `expiresAt` integer, required: Unix epoch milliseconds.

## Other responses

- `401`: Missing or expired OAuth token.
- `403`: Invalid scope, blocked agent or first-party client.
- `422`: Input, grant, billing, idempotency or phone availability failure.
- `429`: Agent REST local quota exceeded; honor Retry-After.

---

[API](https://skmtc.dev/myself/apis/myself-md-public-discovery-api.md) · [All operations](https://skmtc.dev/myself/apis/myself-md-public-discovery-api/llms.txt) · [OpenAPI document](https://skmtc.dev/myself/apis/myself-md-public-discovery-api/revisions/1bb902052126?raw)