> ## 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. # Get a contact > Fetch one Instagram contact by ID with full profile data, custom attributes, assigned tags, and a paginated interaction timeline for review. This endpoint returns one complete contact record and a page of its activity timeline. Use the contact UUID from [List contacts](/api/v1/contacts/list) as `contactId`. ## 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, and `contactId` must belong to that account. This endpoint includes personally identifiable information (PII) and is audited. The API fails without returning the contact if it cannot record the required audit entry. ## Returned data The `contact` object contains every field returned by the contact list, including `email`, `phone`, `biography`, `website`, `tags`, `attributes`, `instagram_profile_url`, and `send_instagram_dm_url`. It also contains a `timeline` object. See [List contacts](/api/v1/contacts/list#returned-data) for the complete field groups and enum meanings. The `timeline.items` array can contain these event types: * `first_contact`: levios recorded the contact's first activity. * `dm_sent`: a direct message was sent. * `dm_failed`: a direct message failed. * `tag_applied`: a tag was added to the contact. * `attribute_captured`: a contact attribute was captured. Each timeline item includes `id`, `type`, and `timestamp`. ## Example request ```bash theme={null} curl --get \ --url "https://levios.app/api/v1/contacts/${LEVIOS_CONTACT_ID}" \ --header "Authorization: Bearer ${LEVIOS_API_KEY}" \ --data-urlencode "account_id=${LEVIOS_ACCOUNT_ID}" \ --data-urlencode 'timeline_limit=25' ``` ## Timeline pagination Set `timeline_limit` to a value from 1 through 50. When `contact.timeline.next_cursor` is not `null`, send it unchanged as `timeline_cursor` with the same `account_id` and `contactId`. Stop when the cursor is `null`. Treat timeline cursors as opaque. Do not reuse a cursor for another contact or account. Because this response includes personal data, avoid writing the full payload to logs, analytics events, or error reports. ## OpenAPI ````yaml openapi/v1.json GET /api/v1/contacts/{contactId} openapi: 3.1.0 info: title: levios public API version: '1' servers: - url: https://levios.app security: - bearerAuth: [] paths: /api/v1/contacts/{contactId}: get: tags: - contact summary: Get a contact description: >- Returns one contact with profile data, attributes, tags, and a paginated interaction timeline. operationId: contacts.get parameters: - name: contactId in: path required: true schema: type: string format: uuid - name: account_id in: query required: true schema: type: string format: uuid - name: timeline_cursor in: query required: false schema: type: string minLength: 1 maxLength: 2048 - name: timeline_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/PublicContactDetailResult' '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 '404': 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_contact_not_found correlation_id: type: string message: type: string enum: - The requested contact was not found. 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_invalid_cursor correlation_id: type: string message: type: string enum: - The contact timeline cursor is invalid. 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: PublicContactDetailResult: $ref: cb9156d2-9e83-4383-b8e2-96efb1e5d550 $defs: PublicContactDetailResult: additionalProperties: false properties: contact: 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 timeline: additionalProperties: false properties: items: items: additionalProperties: false properties: id: maxLength: 256 minLength: 1 type: string timestamp: format: date-time type: string type: description: >- Values: `attribute_captured`: a contact attribute was captured; `dm_failed`: a direct message failed; `dm_sent`: a direct message was sent; `first_contact`: the first contact activity was recorded; `tag_applied`: a tag was added to the contact. enum: - dm_sent - dm_failed - tag_applied - attribute_captured - first_contact type: string required: - id - type - timestamp type: object maxItems: 50 type: array next_cursor: anyOf: - maxLength: 1024 minLength: 1 type: string - type: 'null' required: - items - next_cursor type: object 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 - timeline type: object required: - contact type: object $id: https://levios.app/schemas/public-contact-detail-result-v1 $schema: https://json-schema.org/draft/2019-09/schema# title: PublicContactDetailResult 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.