> ## Documentation Index > Fetch the complete documentation index at: https://docs.levios.app/llms.txt > Use this file to discover all available pages before exploring further. # List contacts > List complete Instagram contact records for one account, or find the exact match for an Instagram username, with cursor pagination. This endpoint returns complete contact records for one Instagram account. Use it to build a contact index, synchronize contact data, or find a contact by an exact Instagram username. ## Access Your API key needs the `contacts:read_pii` scope. The `account_id` query parameter must identify an Instagram account that the key can access. The standard contact endpoints already include personally identifiable information (PII). There are no separate PII variants in API v1. Contact reads are audited, and the API fails without returning contact data if it cannot record the required audit entry. ## Returned data Each item contains these field groups: | Data | Fields | | - | - | | Identity | `id`, `account_id`, `instagram_user_id`, `username`, `name` | | Instagram profile | `profile_picture_url`, `biography`, `website`, `followers_count`, `follows_count`, `media_count`, `account_type`, `is_verified`, `is_user_follow_business` | | Contact and delivery | `email`, `phone`, `opt_out`, `opt_out_at`, `blocked`, `blocked_at` | | Enrichment | `enrichment_status`, `last_enriched_at`, `last_enrichment_attempt_at` | | Activity timestamps | `first_seen_at`, `last_seen_at`, `created_at`, `updated_at` | | Related data | `tags`, `attributes` | | Instagram actions | `instagram_profile_url`, `send_instagram_dm_url` | `tags` contains up to 100 assigned tags with a stable UUID and normalized name. `attributes` contains up to 1,000 captured values with `id`, `key`, `value`, `source`, `source_ref`, `created_at`, and `updated_at`. The `source` enum explains how an attribute was recorded: * `capture`: an automation capture rule recorded the value. * `lead_capture`: the contact provided the value in a lead-capture step. * `manual`: someone set the value manually. The `account_type` enum can be `PERSONAL`, `BUSINESS`, `CREATOR`, or `UNKNOWN`. It can also be `null` when Instagram has not returned an account type. The `enrichment_status` enum describes the profile data: * `pending`: profile enrichment has not finished. * `fresh`: the enrichment data is current. * `stale`: the enrichment data needs to be refreshed. * `failed`: the most recent enrichment attempt failed. Nullable fields that are not available return `null`. This includes PII fields such as `email` and `phone`. The list projection does not include activity timelines. Use [Get a contact](/api/v1/contacts/get) when you also need `timeline`. ## Instagram action URLs levios derives two read-only URLs from the canonical `username`: * `instagram_profile_url`, for example `https://instagram.com/levios_demo_account` * `send_instagram_dm_url`, for example `https://ig.me/m/levios_demo_account` Both fields are `null` when the contact has no valid Instagram username. You can pass these URLs to a browser-capable client to open the profile or start a direct message. ## Find an exact Instagram username Set the optional `instagram_username` query parameter to an exact username. Matching is case-insensitive, and one leading `@` is accepted. Whitespace, partial matches, and malformed Instagram usernames are rejected. ```bash theme={null} curl --get \ --url 'https://levios.app/api/v1/contacts' \ --header "Authorization: Bearer ${LEVIOS_API_KEY}" \ --data-urlencode "account_id=${LEVIOS_ACCOUNT_ID}" \ --data-urlencode 'instagram_username=@levios_demo_account' ``` The filter performs an exact lookup, not a search by prefix or substring. ## Pagination Set `limit` to a value from 1 through 50. When `next_cursor` is not `null`, send it unchanged as `cursor` with the same `account_id` and `instagram_username` filter. Treat the cursor as opaque and stop when `next_cursor` is `null`. Do not reuse a cursor with another account or username filter. Because this response includes personal data, avoid writing full payloads to logs, analytics events, or error reports. ## OpenAPI ````yaml openapi/v1.json GET /api/v1/contacts openapi: 3.1.0 info: title: levios public API version: '1' servers: - url: https://levios.app security: - bearerAuth: [] paths: /api/v1/contacts: get: tags: - contact summary: List contacts description: >- Returns full contact records for one Instagram account, with an optional exact Instagram username filter. operationId: contacts.list parameters: - name: account_id in: query required: true schema: type: string format: uuid - name: cursor in: query required: false schema: type: string minLength: 1 maxLength: 1024 - name: instagram_username in: query required: false schema: $ref: '#/components/schemas/PublicInstagramUsernameFilter' - name: limit in: query required: false schema: type: string responses: '200': description: Successful response. headers: X-Correlation-ID: description: Correlation identifier for this request. schema: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ content: application/json: schema: $ref: '#/components/schemas/PublicContactPage' '400': description: Error response. headers: X-Correlation-ID: description: Correlation identifier for this request. schema: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ content: application/json: schema: oneOf: - type: object properties: error: type: object properties: code: type: string enum: - api_invalid_content_length correlation_id: type: string message: type: string enum: - Invalid Content-Length. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_invalid_json correlation_id: type: string message: type: string enum: - The request body is not valid JSON. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_invalid_request_url correlation_id: type: string message: type: string enum: - The request URL is invalid. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_invalid_utf8 correlation_id: type: string message: type: string enum: - The request body is not valid UTF-8. required: - code - message additionalProperties: false required: - error additionalProperties: false '401': description: Error response. headers: X-Correlation-ID: description: Correlation identifier for this request. schema: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ WWW-Authenticate: description: API key Bearer challenge. schema: type: string enum: - Bearer content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - api_unauthorized correlation_id: type: string message: type: string enum: - Authentication required. required: - code - message additionalProperties: false required: - error additionalProperties: false '403': description: Error response. headers: X-Correlation-ID: description: Correlation identifier for this request. schema: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ content: application/json: schema: oneOf: - type: object properties: error: type: object properties: code: type: string enum: - api_account_not_granted correlation_id: type: string message: type: string enum: - >- This credential is not authorized for the request. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_forbidden correlation_id: type: string message: type: string enum: - >- This credential is not authorized for the request. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_scope_denied correlation_id: type: string message: type: string enum: - >- This credential is not authorized for the request. required: - code - message additionalProperties: false required: - error additionalProperties: false '413': description: Error response. headers: X-Correlation-ID: description: Correlation identifier for this request. schema: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ content: application/json: schema: oneOf: - type: object properties: error: type: object properties: code: type: string enum: - api_body_too_large correlation_id: type: string message: type: string enum: - The JSON request body exceeds 1 MiB. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_json_too_deep correlation_id: type: string message: type: string enum: - The JSON request body exceeds maximum depth. required: - code - message additionalProperties: false required: - error additionalProperties: false '415': description: Error response. headers: X-Correlation-ID: description: Correlation identifier for this request. schema: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - api_unsupported_media_type correlation_id: type: string message: type: string enum: - Content-Type must be application/json. required: - code - message additionalProperties: false required: - error additionalProperties: false '422': description: Error response. headers: X-Correlation-ID: description: Correlation identifier for this request. schema: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ content: application/json: schema: oneOf: - type: object properties: error: type: object properties: code: type: string enum: - api_instagram_username_invalid correlation_id: type: string message: type: string enum: - The Instagram username is malformed. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_invalid_cursor correlation_id: type: string message: type: string enum: - >- The contact cursor is invalid for this account and filter. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_invalid_limit correlation_id: type: string message: type: string enum: - >- The page limit must be an integer between 1 and 50. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_validation_error correlation_id: type: string details: type: object properties: issues: type: array items: type: object properties: code: type: string minLength: 1 maxLength: 64 path: type: array items: type: integer minimum: 0 maxItems: 16 required: - code - path additionalProperties: false maxItems: 32 required: - issues additionalProperties: false message: type: string enum: - The request does not match the declared schema. required: - code - message additionalProperties: false required: - error additionalProperties: false '429': description: Error response. headers: X-Correlation-ID: description: Correlation identifier for this request. schema: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - rate_limited correlation_id: type: string message: type: string enum: - Rate limit exceeded. required: - code - message additionalProperties: false required: - error additionalProperties: false '500': description: Error response. headers: X-Correlation-ID: description: Correlation identifier for this request. schema: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ content: application/json: schema: oneOf: - type: object properties: error: type: object properties: code: type: string enum: - api_internal_error correlation_id: type: string message: type: string enum: - The request could not be completed. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_invalid_projection correlation_id: type: string message: type: string enum: - The contact projection is invalid. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_projection_too_large correlation_id: type: string message: type: string enum: - >- The projected result exceeds the result byte limit. required: - code - message additionalProperties: false required: - error additionalProperties: false '503': description: Error response. headers: X-Correlation-ID: description: Correlation identifier for this request. schema: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ content: application/json: schema: oneOf: - type: object properties: error: type: object properties: code: type: string enum: - api_account_resolution_unavailable correlation_id: type: string message: type: string enum: - The reachable account set could not be read. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_audit_unavailable correlation_id: type: string message: type: string enum: - The security audit log is unavailable. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_contact_read_unavailable correlation_id: type: string message: type: string enum: - The contact data could not be read. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - rate_limiter_unavailable correlation_id: type: string message: type: string enum: - Rate limiter unavailable. required: - code - message additionalProperties: false required: - error additionalProperties: false components: schemas: PublicInstagramUsernameFilter: $ref: 0b1de94a-6d70-4bb1-b3d7-c9cd1beef334 $defs: PublicInstagramUsernameFilter: description: >- Exact Instagram username. One leading @ is accepted, whitespace is rejected, and matching is case-insensitive. pattern: >- ^@?(?=[A-Za-z0-9._]{1,30}$)(?=[A-Za-z0-9._]*[A-Za-z0-9][A-Za-z0-9._]*$)(?!\.)(?![A-Za-z0-9._]*\.\.)(?![A-Za-z0-9._]*\.$)[A-Za-z0-9._]+$ type: string $id: https://levios.app/schemas/public-instagram-username-filter-v1 $schema: https://json-schema.org/draft/2019-09/schema# title: PublicInstagramUsernameFilter x-levios-max-serialized-bytes: 65536 x-levios-schema-version: 1 PublicContactPage: $ref: 24b9314c-bcdf-4fca-9c58-f874db71724c $defs: PublicContactPage: additionalProperties: false properties: items: items: additionalProperties: false properties: account_id: format: uuid pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ type: string account_type: anyOf: - description: >- Values: `BUSINESS`: an Instagram business account; `CREATOR`: an Instagram creator account; `PERSONAL`: an Instagram personal account; `UNKNOWN`: the Instagram account type is unavailable. enum: - PERSONAL - BUSINESS - CREATOR - UNKNOWN type: string - type: 'null' attributes: items: additionalProperties: false properties: created_at: format: date-time type: string id: pattern: ^[1-9][0-9]{0,18}$ type: string key: maxLength: 100 minLength: 1 type: string source: description: >- Values: `capture`: derived from an automation capture rule; `lead_capture`: provided by the contact through a lead-capture step; `manual`: set manually. enum: - capture - lead_capture - manual type: string source_ref: anyOf: - maxLength: 200 minLength: 1 type: string - type: 'null' updated_at: format: date-time type: string value: anyOf: - maxLength: 10000 minLength: 0 type: string - type: 'null' required: - id - key - value - source - source_ref - created_at - updated_at type: object maxItems: 1000 type: array biography: anyOf: - maxLength: 100000 minLength: 1 type: string - type: 'null' blocked: type: boolean blocked_at: anyOf: - format: date-time type: string - type: 'null' created_at: format: date-time type: string email: anyOf: - maxLength: 320 minLength: 1 type: string - type: 'null' enrichment_status: description: >- Values: `failed`: the most recent enrichment attempt failed; `fresh`: the enrichment data is current; `pending`: profile enrichment has not finished; `stale`: the enrichment data needs to be refreshed. enum: - pending - fresh - stale - failed type: string first_seen_at: format: date-time type: string followers_count: anyOf: - maximum: 9007199254740991 minimum: 0 type: integer - type: 'null' follows_count: anyOf: - maximum: 9007199254740991 minimum: 0 type: integer - type: 'null' id: format: uuid pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ type: string instagram_profile_url: anyOf: - format: uri pattern: ^https://instagram\.com/[a-z0-9._]{1,30}$ type: string - type: 'null' description: >- Server-derived profile URL for the canonical username; null when username is absent or invalid. readOnly: true instagram_user_id: maxLength: 100 minLength: 1 type: string is_user_follow_business: anyOf: - type: boolean - type: 'null' is_verified: anyOf: - type: boolean - type: 'null' last_enriched_at: anyOf: - format: date-time type: string - type: 'null' last_enrichment_attempt_at: anyOf: - format: date-time type: string - type: 'null' last_seen_at: format: date-time type: string media_count: anyOf: - maximum: 9007199254740991 minimum: 0 type: integer - type: 'null' name: anyOf: - maxLength: 120 minLength: 1 type: string - type: 'null' opt_out: type: boolean opt_out_at: anyOf: - format: date-time type: string - type: 'null' phone: anyOf: - maxLength: 64 minLength: 1 type: string - type: 'null' profile_picture_url: anyOf: - maxLength: 2048 minLength: 1 type: string - type: 'null' send_instagram_dm_url: anyOf: - format: uri pattern: ^https://ig\.me/m/[a-z0-9._]{1,30}$ type: string - type: 'null' description: >- Server-derived Instagram DM URL for the canonical username; null when username is absent or invalid. readOnly: true tags: items: additionalProperties: false properties: id: description: >- Stable public tag UUID. Internal numeric catalog IDs are never exposed. format: uuid pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ type: string name: description: >- Normalized tag name: trimmed, with consecutive whitespace collapsed to one ASCII space. maxLength: 50 minLength: 1 pattern: >- ^(?!.*\s{2})(?!\s)(?!.*\s$)(?!.*[\u0000-\u001F\u007F]).+$ type: string required: - id - name type: object maxItems: 100 type: array updated_at: format: date-time type: string username: anyOf: - pattern: >- ^(?=[a-z0-9._]{1,30}$)(?=[a-z0-9._]*[a-z0-9][a-z0-9._]*$)(?!\.)(?![a-z0-9._]*\.\.)(?![a-z0-9._]*\.$)[a-z0-9._]+$ type: string - type: 'null' website: anyOf: - maxLength: 2048 minLength: 1 type: string - type: 'null' required: - id - account_id - instagram_user_id - username - instagram_profile_url - send_instagram_dm_url - name - profile_picture_url - biography - website - followers_count - follows_count - media_count - account_type - is_verified - is_user_follow_business - email - phone - opt_out - opt_out_at - blocked - blocked_at - enrichment_status - first_seen_at - last_seen_at - last_enriched_at - last_enrichment_attempt_at - created_at - updated_at - tags - attributes type: object maxItems: 50 type: array next_cursor: anyOf: - maxLength: 1024 minLength: 1 type: string - type: 'null' required: - items - next_cursor type: object $id: https://levios.app/schemas/public-contact-page-v1 $schema: https://json-schema.org/draft/2019-09/schema# title: PublicContactPage x-levios-max-serialized-bytes: 65536 x-levios-schema-version: 1 securitySchemes: bearerAuth: type: http scheme: bearer description: Levios API key sent as a Bearer token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.