> ## Documentation Index > Fetch the complete documentation index at: https://docs.lighton.ai/llms.txt > Use this file to discover all available pages before exploring further. # List companies > This endpoint allows users to list companies based on their permissions. Access levels: - SysAdmin/Account Manager/DPO Admin: Can view all companies - Company Admin: Can view their own company only - Company DPO: Read-only access to their own company - User: No access Supports pagination and search functionality. ## OpenAPI ````yaml /api-reference/openapi-v3-instance.yaml get /api/v3/instance/companies openapi: 3.1.0 info: title: LightOn API version: 3.15.0 (v3-instance) description: >- LightOn gives you an API to search, parse, and ingest documents at scale. Build knowledge-retrieval pipelines without managing vector databases or OCR models. servers: - url: https://paradigm.lighton.ai security: [] tags: - name: Models description: Operations about AI models - name: Workspaces description: Operations about workspaces - name: Users description: Operations about users - name: User Groups description: Operations about user groups - name: Companies description: Operations about companies paths: /api/v3/instance/companies: get: tags: - Companies summary: List companies description: |- This endpoint allows users to list companies based on their permissions. Access levels: - SysAdmin/Account Manager/DPO Admin: Can view all companies - Company Admin: Can view their own company only - Company DPO: Read-only access to their own company - User: No access Supports pagination and search functionality. operationId: api_v3_instance_companies_list parameters: - in: query name: has_usage schema: type: boolean description: >- Filter companies by metered usage. `true` returns only companies with at least one recorded usage event; `false` returns companies with none. - in: query name: page schema: type: integer description: 'Page number (default: 1)' - in: query name: search schema: type: string description: Filter by company name (case-insensitive) - in: query name: tier schema: type: string enum: - business - free - pay-as-you-go description: >- Commercial tier for this company. Drives entitlements and billing posture. * `free` - Free * `pay-as-you-go` - Pay-as-you-go * `business` - Business responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedCompanyListResponseList' description: >- List of companies with DRF pagination (count, next, previous, results) '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: >- https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '503': description: >- API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' security: - bearerAuth: [] - {} components: schemas: PaginatedCompanyListResponseList: type: object required: - count - results properties: count: type: integer example: 123 next: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=4 previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=2 results: type: array items: $ref: '#/components/schemas/CompanyListResponse' APIV3ErrorResponse: type: object properties: id: type: - string - 'null' description: >- Job/resource id when one already exists (useful for async error diagnosis); null otherwise. code: type: integer description: HTTP status code error: type: string description: Error code used by the UI as a translation key detail: type: string description: Human-readable error message for developers doc_url: type: string description: Link to the error-code documentation page required: - code - detail - doc_url - error - id ServiceMaintenance503: type: object description: >- Returned by the maintenance middleware when the requested endpoint is blocked. required: - detail - error - mode properties: detail: type: string example: System is under maintenance. error: type: string example: service_maintenance mode: type: string enum: - full_shutdown - warning_banner description: >- `full_shutdown` blocks all traffic; `warning_banner` also blocks and shows a dismissible toast. reason: type: string description: Operator-supplied maintenance reason, if any. started_at: type: string format: date-time endpoint_category_names: type: array items: type: string description: >- Non-empty only for category-scoped periods. Empty means all endpoints are affected. CompanyListResponse: type: object description: Serializer for listing companies properties: id: type: integer readOnly: true name: type: string description: The name of the company registered in the instance. maxLength: 255 dpo_email: type: - string - 'null' format: email description: Contact email displayed in user profiles for data privacy inquiries. maxLength: 254 max_users: type: integer maximum: 2147483647 minimum: -2147483648 description: Maximum allowed active users for this company license. created_at: type: string format: date-time readOnly: true login_method: allOf: - $ref: '#/components/schemas/LoginMethodEnum' description: |- Authentication method(s) allowed for users in this company. * `password` - Password * `sso` - Single Sign On * `ldap` - LDAP tier: allOf: - $ref: '#/components/schemas/TierEnum' description: >- Commercial tier for this company. Drives entitlements and billing posture. * `free` - Free * `pay-as-you-go` - Pay-as-you-go * `business` - Business period_spend_eur: type: - string - 'null' description: >- Spend accrued in the open billing period (current calendar month), in EUR. Counter usage plus the tier-aware storage charge — the same figure the company's own usage page shows. `null` when the metering backend is unavailable. readOnly: true required: - created_at - id - name - period_spend_eur LoginMethodEnum: enum: - password - sso - ldap type: string description: |- * `password` - Password * `sso` - Single Sign On * `ldap` - LDAP TierEnum: enum: - free - pay-as-you-go - business type: string description: |- * `free` - Free * `pay-as-you-go` - Pay-as-you-go * `business` - Business securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer authentication header of the form `Bearer `, where `` is your auth token. ````