> ## 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 contact tags > List reusable contact tags defined for one Instagram account, with cursor pagination and tag names ready for building selectors and filters. This endpoint returns the reusable tag catalog for one Instagram account. Use the returned tag UUIDs when you add or remove tags from contacts. Automation configuration fields reference the normalized tag `name`, not the UUID. ## Access Your API key needs the `contacts:write` scope. The `account_id` query parameter must identify an Instagram account that the key can access. All contact-tag catalog and assignment operations use `contacts:write`, including this read operation. ## Returned data Each item contains: * `id`: the stable public UUID for the tag. * `name`: the normalized tag name. Internal catalog IDs and usage counts are not exposed. ## 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`. Treat the cursor as opaque and stop when `next_cursor` is `null`. ## Example request ```bash theme={null} curl --get \ --url 'https://levios.app/api/v1/contact-tags' \ --header "Authorization: Bearer ${LEVIOS_API_KEY}" \ --data-urlencode "account_id=${LEVIOS_ACCOUNT_ID}" \ --data-urlencode 'limit=50' ``` ## OpenAPI ````yaml openapi/v1.json GET /api/v1/contact-tags openapi: 3.1.0 info: title: levios public API version: '1' servers: - url: https://levios.app security: - bearerAuth: [] paths: /api/v1/contact-tags: get: tags: - contact_tag summary: List contact tags description: Returns a cursor-paginated list of tags for one Instagram account. operationId: contact_tags.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: 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/PublicContactTagPage' '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_invalid_cursor correlation_id: type: string message: type: string enum: - >- The contact-tag cursor is invalid for this account. 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-tag 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_tag_read_unavailable correlation_id: type: string message: type: string enum: - The contact-tag catalog 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: PublicContactTagPage: $ref: aecbd1b3-7eaa-4f7b-8b07-dab83d8ac2d1 $defs: PublicContactTagPage: additionalProperties: false properties: items: 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: 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-tag-page-v1 $schema: https://json-schema.org/draft/2019-09/schema# title: PublicContactTagPage 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.