# List companies

`GET /v0/companies`

Returns a keyset-paginated list of active, commercially cleared companies with open jobs. Filters combine with AND across dimensions and OR within each repeated dimension.

## Authentication

`bearerAuth` (http bearer) — Organisation API key supplied only through the Authorization header. Required scopes: `companies:read`.

## Request

### cURL

```shell
curl --request GET \
  --url "https://api.luranta.com/v0/companies" \
  --header "Authorization: Bearer $LURANTA_API_KEY" \
  --header "Accept: application/json" \
  --get \
  --data-urlencode "query=Acme" \
  --data-urlencode "countries=GB"
```

### TypeScript

```ts
const url = new URL("https://api.luranta.com/v0/companies")
url.searchParams.append("query", "Acme")
url.searchParams.append("countries", "GB")

const response = await fetch(url, {
  headers: {
    Authorization: `Bearer ${process.env.LURANTA_API_KEY}`,
  },
})

const result = await response.json()
```

### Python

```python
import os
import requests

response = requests.get(
    "https://api.luranta.com/v0/companies",
    params=[
        ("query", "Acme"),
        ("countries", "GB"),
    ],
    headers={"Authorization": f"Bearer {os.environ['LURANTA_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
result = response.json()
```

## Parameters

### `query`

`string` · query · optional

Company-name query using case-insensitive substring and similarity matching. Normalized to Unicode NFC with folded whitespace; 1–200 characters.

- Type: `string`
  - Description: Company-name query using case-insensitive substring and similarity matching. Normalized to Unicode NFC with folded whitespace; 1–200 characters.
  - Examples: `["Acme"]`
  - Maximum length: `200`
  - Minimum length: `1`

Examples

- example-1: `Acme`

### `countries`

`string[]` · query · optional · style `form` · explode `true`

Uppercase ISO 3166-1 alpha-2 country codes. Repeat the parameter to match any supplied country; maximum 50.

- Type: `string[]`
  - Description: Uppercase ISO 3166-1 alpha-2 country codes. Repeat the parameter to match any supplied country; maximum 50.
  - Default: `[]`
  - Examples: `[["GB"]]`
  - Maximum items: `50`
  - Items:
    - Type: `string`
      - Pattern: `^[A-Z]{2}$`

Examples

- example-1: `["GB"]`

### `industries`

`string[]` · query · optional · style `form` · explode `true`

Stable industry codes assigned to the company from the versioned Luranta industry taxonomy. Repeat the parameter to match any supplied code; maximum 50. Discover values with GET /v0/taxonomies/industries.

[Browse available values](/reference/getIndustryTaxonomy).

- Type: `string[]`
  - Description: Stable industry codes assigned to the company from the versioned Luranta industry taxonomy. Repeat the parameter to match any supplied code; maximum 50. Discover values with GET /v0/taxonomies/industries.
  - Default: `[]`
  - Examples: `[["technology"]]`
  - Maximum items: `50`
  - Items:
    - Type: `string`
      - Maximum length: `160`
      - Minimum length: `1`
      - Pattern: `^[a-z0-9]+(?:[-_.][a-z0-9]+)*$`

Examples

- example-1: `["technology"]`

### `sort`

`string` · query · optional

Ordering field: name, open_jobs, or updated. Defaults to name.

Available options: `name`, `open_jobs`, `updated`.

- Type: `string`
  - Description: Ordering field: name, open_jobs, or updated. Defaults to name.
  - Allowed values: `["name","open_jobs","updated"]`
  - Default: `name`
  - Examples: `["name"]`

Examples

- example-1: `name`

### `direction`

`string` · query · optional

Sort direction for the selected ordering field. UUIDv7 ID breaks ties. Defaults to asc.

Available options: `asc`, `desc`.

- Type: `string`
  - Description: Sort direction for the selected ordering field. UUIDv7 ID breaks ties. Defaults to asc.
  - Allowed values: `["asc","desc"]`
  - Default: `asc`
  - Examples: `["asc"]`

Examples

- example-1: `asc`

### `cursor`

`string` · query · optional

Opaque keyset cursor from next_cursor. Reuse it with unchanged filters, sort, and direction; limit may change. Expires after 24 hours.

- Type: `string`
  - Description: Opaque keyset cursor from next_cursor. Reuse it with unchanged filters, sort, and direction; limit may change. Expires after 24 hours.
  - Maximum length: `1000`
  - Minimum length: `1`

### `limit`

`integer` · query · optional

Maximum resources to return, from 1 to 100. Defaults to 20.

- Type: `integer`
  - Description: Maximum resources to return, from 1 to 100. Defaults to 20.
  - Default: `20`
  - Examples: `[20]`
  - Maximum: `100`
  - Minimum: `1`

Examples

- example-1: `20`

## Responses

### 200

A page of matching companies. The list may be empty.

#### Headers

##### `Luranta-Cost-USD`

`string` · optional

Credit consumed as a USD decimal string. Present only on successful billable responses.

- Type: `string`
  - Pattern: `^(?:0|[1-9]\d*)\.\d{2,6}$`

##### `Luranta-Credit-Balance-USD`

`string` · optional

Organisation credit remaining after settlement. Present only on successful billable responses.

- Type: `string`
  - Pattern: `^(?:0|[1-9]\d*)\.\d{2,6}$`

##### `Luranta-Resources-Returned`

`integer` · optional

Number of resources returned and charged. Present only on successful billable responses.

- Type: `integer`
  - Minimum: `0`

##### `traceparent`

`string` · required

W3C trace context generated for this request attempt.

- Type: `string`
  - Pattern: `^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$`

##### `X-Request-Id`

`string<uuid>` · required

Unique UUIDv7 identifier for this request attempt.

- Type: `string<uuid>`
  - Format: `uuid`

#### application/json

- Type: `CompanyList`
  - Component: [`CompanyList`](/reference/schemas#CompanyList)
  - Additional properties: `forbidden`
  - Properties:
    - `data` (required):
      - Type: `object[]`
        - Maximum items: `100`
        - Items:
          - Type: `object`
            - Additional properties: `forbidden`
            - Properties:
              - `country` (required):
                - Type: `string | null`
                  - anyOf:
                    - Type: `string`
                      - Pattern: `^[A-Z]{2}$`
                    - Type: `null`
              - `id` (required):
                - Type: `string<uuid>`
                  - Format: `uuid`
                  - Pattern: `^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$`
              - `industries` (required):
                - Type: `string[]`
                  - Maximum items: `20`
                  - Items:
                    - Type: `string`
                      - Maximum length: `160`
                      - Minimum length: `1`
                      - Pattern: `^[a-z0-9]+(?:[-_.][a-z0-9]+)*$`
              - `logo_url` (required):
                - Type: `string<uri> | null`
                  - anyOf:
                    - Type: `string<uri>`
                      - Format: `uri`
                      - Maximum length: `2048`
                    - Type: `null`
              - `merged_into_id` (required):
                - Type: `string<uuid> | null`
                  - anyOf:
                    - Type: `string<uuid>`
                      - Format: `uuid`
                      - Pattern: `^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$`
                    - Type: `null`
              - `name` (required):
                - Type: `string`
                  - Maximum length: `240`
                  - Minimum length: `1`
              - `object` (required):
                - Type: `string`
                  - Constant: `company`
              - `open_job_count` (required):
                - Type: `integer`
                  - Maximum: `9007199254740991`
                  - Minimum: `0`
              - `status` (required):
                - Type: `string`
                  - Allowed values: `["active","inactive","merged"]`
              - `type` (required):
                - Type: `string`
                  - Allowed values: `["company","brand","government","education","healthcare","nonprofit","partnership","agency","other"]`
              - `website_url` (required):
                - Type: `string<uri> | null`
                  - anyOf:
                    - Type: `string<uri>`
                      - Format: `uri`
                      - Maximum length: `2048`
                    - Type: `null`
    - `has_more` (required):
      - Type: `boolean`
    - `next_cursor` (required):
      - Type: `string | null`
        - anyOf:
          - Type: `string`
            - Maximum length: `1000`
          - Type: `null`
    - `object` (required):
      - Type: `string`
        - Constant: `list`

### 400

The request contains an invalid parameter, parameter combination, or cursor.

This response uses [Problem Details](/reference/problem-details).

#### Headers

##### `traceparent`

`string` · required

W3C trace context generated for this request attempt.

- Type: `string`
  - Pattern: `^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$`

##### `X-Request-Id`

`string<uuid>` · required

Unique UUIDv7 identifier for this request attempt.

- Type: `string<uuid>`
  - Format: `uuid`

#### application/problem+json

Errors follow [Problem Details](/reference/problem-details).

- Type: `ProblemDetails`
  - Component: [`ProblemDetails`](/reference/problem-details)
  - Additional properties: `forbidden`
  - Properties:
    - `available_credit_usd` (optional):
      - Type: `string`
        - Pattern: `^(?:0|[1-9]\d*)\.\d{2,6}$`
    - `code` (required):
      - Type: `string`
        - Maximum length: `80`
        - Minimum length: `1`
    - `detail` (required):
      - Type: `string`
        - Maximum length: `1000`
        - Minimum length: `1`
    - `errors` (optional):
      - Type: `object[]`
        - Maximum items: `100`
        - Items:
          - Type: `object`
            - Additional properties: `forbidden`
            - Properties:
              - `code` (required):
                - Type: `string`
                  - Maximum length: `80`
                  - Minimum length: `1`
              - `message` (required):
                - Type: `string`
                  - Maximum length: `500`
                  - Minimum length: `1`
              - `pointer` (required):
                - Type: `string`
                  - Pattern: `^\/.*`
    - `instance` (required):
      - Type: `string`
        - Pattern: `^\/.*`
    - `param` (optional):
      - Type: `string`
        - Maximum length: `160`
        - Minimum length: `1`
    - `request_id` (required):
      - Type: `string<uuid>`
        - Format: `uuid`
        - Pattern: `^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$`
    - `required_credit_usd` (optional):
      - Type: `string`
        - Pattern: `^(?:0|[1-9]\d*)\.\d{2,6}$`
    - `retryable` (required):
      - Type: `boolean`
    - `status` (required):
      - Type: `integer`
        - Maximum: `599`
        - Minimum: `400`
    - `title` (required):
      - Type: `string`
        - Maximum length: `120`
        - Minimum length: `1`
    - `top_up_url` (optional):
      - Type: `string<uri>`
        - Format: `uri`
        - Maximum length: `2048`
    - `type` (required):
      - Type: `string<uri>`
        - Format: `uri`
        - Maximum length: `2048`

### 401

The organisation API key is missing, invalid, expired, or revoked.

This response uses [Problem Details](/reference/problem-details).

#### Headers

##### `traceparent`

`string` · required

W3C trace context generated for this request attempt.

- Type: `string`
  - Pattern: `^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$`

##### `X-Request-Id`

`string<uuid>` · required

Unique UUIDv7 identifier for this request attempt.

- Type: `string<uuid>`
  - Format: `uuid`

#### application/problem+json

Errors follow [Problem Details](/reference/problem-details).

- Type: `ProblemDetails`
  - Component: [`ProblemDetails`](/reference/problem-details)
  - Additional properties: `forbidden`
  - Properties:
    - `available_credit_usd` (optional):
      - Type: `string`
        - Pattern: `^(?:0|[1-9]\d*)\.\d{2,6}$`
    - `code` (required):
      - Type: `string`
        - Maximum length: `80`
        - Minimum length: `1`
    - `detail` (required):
      - Type: `string`
        - Maximum length: `1000`
        - Minimum length: `1`
    - `errors` (optional):
      - Type: `object[]`
        - Maximum items: `100`
        - Items:
          - Type: `object`
            - Additional properties: `forbidden`
            - Properties:
              - `code` (required):
                - Type: `string`
                  - Maximum length: `80`
                  - Minimum length: `1`
              - `message` (required):
                - Type: `string`
                  - Maximum length: `500`
                  - Minimum length: `1`
              - `pointer` (required):
                - Type: `string`
                  - Pattern: `^\/.*`
    - `instance` (required):
      - Type: `string`
        - Pattern: `^\/.*`
    - `param` (optional):
      - Type: `string`
        - Maximum length: `160`
        - Minimum length: `1`
    - `request_id` (required):
      - Type: `string<uuid>`
        - Format: `uuid`
        - Pattern: `^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$`
    - `required_credit_usd` (optional):
      - Type: `string`
        - Pattern: `^(?:0|[1-9]\d*)\.\d{2,6}$`
    - `retryable` (required):
      - Type: `boolean`
    - `status` (required):
      - Type: `integer`
        - Maximum: `599`
        - Minimum: `400`
    - `title` (required):
      - Type: `string`
        - Maximum length: `120`
        - Minimum length: `1`
    - `top_up_url` (optional):
      - Type: `string<uri>`
        - Format: `uri`
        - Maximum length: `2048`
    - `type` (required):
      - Type: `string<uri>`
        - Format: `uri`
        - Maximum length: `2048`

### 402

The organisation does not have enough credit to reserve this operation.

This response uses [Problem Details](/reference/problem-details).

#### Headers

##### `traceparent`

`string` · required

W3C trace context generated for this request attempt.

- Type: `string`
  - Pattern: `^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$`

##### `X-Request-Id`

`string<uuid>` · required

Unique UUIDv7 identifier for this request attempt.

- Type: `string<uuid>`
  - Format: `uuid`

#### application/problem+json

Errors follow [Problem Details](/reference/problem-details).

- Type: `ProblemDetails`
  - Component: [`ProblemDetails`](/reference/problem-details)
  - Additional properties: `forbidden`
  - Properties:
    - `available_credit_usd` (optional):
      - Type: `string`
        - Pattern: `^(?:0|[1-9]\d*)\.\d{2,6}$`
    - `code` (required):
      - Type: `string`
        - Maximum length: `80`
        - Minimum length: `1`
    - `detail` (required):
      - Type: `string`
        - Maximum length: `1000`
        - Minimum length: `1`
    - `errors` (optional):
      - Type: `object[]`
        - Maximum items: `100`
        - Items:
          - Type: `object`
            - Additional properties: `forbidden`
            - Properties:
              - `code` (required):
                - Type: `string`
                  - Maximum length: `80`
                  - Minimum length: `1`
              - `message` (required):
                - Type: `string`
                  - Maximum length: `500`
                  - Minimum length: `1`
              - `pointer` (required):
                - Type: `string`
                  - Pattern: `^\/.*`
    - `instance` (required):
      - Type: `string`
        - Pattern: `^\/.*`
    - `param` (optional):
      - Type: `string`
        - Maximum length: `160`
        - Minimum length: `1`
    - `request_id` (required):
      - Type: `string<uuid>`
        - Format: `uuid`
        - Pattern: `^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$`
    - `required_credit_usd` (optional):
      - Type: `string`
        - Pattern: `^(?:0|[1-9]\d*)\.\d{2,6}$`
    - `retryable` (required):
      - Type: `boolean`
    - `status` (required):
      - Type: `integer`
        - Maximum: `599`
        - Minimum: `400`
    - `title` (required):
      - Type: `string`
        - Maximum length: `120`
        - Minimum length: `1`
    - `top_up_url` (optional):
      - Type: `string<uri>`
        - Format: `uri`
        - Maximum length: `2048`
    - `type` (required):
      - Type: `string<uri>`
        - Format: `uri`
        - Maximum length: `2048`

### 403

The authenticated organisation lacks the required scope, or the browser origin is not allowed.

This response uses [Problem Details](/reference/problem-details).

#### Headers

##### `traceparent`

`string` · required

W3C trace context generated for this request attempt.

- Type: `string`
  - Pattern: `^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$`

##### `X-Request-Id`

`string<uuid>` · required

Unique UUIDv7 identifier for this request attempt.

- Type: `string<uuid>`
  - Format: `uuid`

#### application/problem+json

Errors follow [Problem Details](/reference/problem-details).

- Type: `ProblemDetails`
  - Component: [`ProblemDetails`](/reference/problem-details)
  - Additional properties: `forbidden`
  - Properties:
    - `available_credit_usd` (optional):
      - Type: `string`
        - Pattern: `^(?:0|[1-9]\d*)\.\d{2,6}$`
    - `code` (required):
      - Type: `string`
        - Maximum length: `80`
        - Minimum length: `1`
    - `detail` (required):
      - Type: `string`
        - Maximum length: `1000`
        - Minimum length: `1`
    - `errors` (optional):
      - Type: `object[]`
        - Maximum items: `100`
        - Items:
          - Type: `object`
            - Additional properties: `forbidden`
            - Properties:
              - `code` (required):
                - Type: `string`
                  - Maximum length: `80`
                  - Minimum length: `1`
              - `message` (required):
                - Type: `string`
                  - Maximum length: `500`
                  - Minimum length: `1`
              - `pointer` (required):
                - Type: `string`
                  - Pattern: `^\/.*`
    - `instance` (required):
      - Type: `string`
        - Pattern: `^\/.*`
    - `param` (optional):
      - Type: `string`
        - Maximum length: `160`
        - Minimum length: `1`
    - `request_id` (required):
      - Type: `string<uuid>`
        - Format: `uuid`
        - Pattern: `^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$`
    - `required_credit_usd` (optional):
      - Type: `string`
        - Pattern: `^(?:0|[1-9]\d*)\.\d{2,6}$`
    - `retryable` (required):
      - Type: `boolean`
    - `status` (required):
      - Type: `integer`
        - Maximum: `599`
        - Minimum: `400`
    - `title` (required):
      - Type: `string`
        - Maximum length: `120`
        - Minimum length: `1`
    - `top_up_url` (optional):
      - Type: `string<uri>`
        - Format: `uri`
        - Maximum length: `2048`
    - `type` (required):
      - Type: `string<uri>`
        - Format: `uri`
        - Maximum length: `2048`

### 404

The requested resource does not exist or is not available to this organisation.

This response uses [Problem Details](/reference/problem-details).

#### Headers

##### `traceparent`

`string` · required

W3C trace context generated for this request attempt.

- Type: `string`
  - Pattern: `^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$`

##### `X-Request-Id`

`string<uuid>` · required

Unique UUIDv7 identifier for this request attempt.

- Type: `string<uuid>`
  - Format: `uuid`

#### application/problem+json

Errors follow [Problem Details](/reference/problem-details).

- Type: `ProblemDetails`
  - Component: [`ProblemDetails`](/reference/problem-details)
  - Additional properties: `forbidden`
  - Properties:
    - `available_credit_usd` (optional):
      - Type: `string`
        - Pattern: `^(?:0|[1-9]\d*)\.\d{2,6}$`
    - `code` (required):
      - Type: `string`
        - Maximum length: `80`
        - Minimum length: `1`
    - `detail` (required):
      - Type: `string`
        - Maximum length: `1000`
        - Minimum length: `1`
    - `errors` (optional):
      - Type: `object[]`
        - Maximum items: `100`
        - Items:
          - Type: `object`
            - Additional properties: `forbidden`
            - Properties:
              - `code` (required):
                - Type: `string`
                  - Maximum length: `80`
                  - Minimum length: `1`
              - `message` (required):
                - Type: `string`
                  - Maximum length: `500`
                  - Minimum length: `1`
              - `pointer` (required):
                - Type: `string`
                  - Pattern: `^\/.*`
    - `instance` (required):
      - Type: `string`
        - Pattern: `^\/.*`
    - `param` (optional):
      - Type: `string`
        - Maximum length: `160`
        - Minimum length: `1`
    - `request_id` (required):
      - Type: `string<uuid>`
        - Format: `uuid`
        - Pattern: `^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$`
    - `required_credit_usd` (optional):
      - Type: `string`
        - Pattern: `^(?:0|[1-9]\d*)\.\d{2,6}$`
    - `retryable` (required):
      - Type: `boolean`
    - `status` (required):
      - Type: `integer`
        - Maximum: `599`
        - Minimum: `400`
    - `title` (required):
      - Type: `string`
        - Maximum length: `120`
        - Minimum length: `1`
    - `top_up_url` (optional):
      - Type: `string<uri>`
        - Format: `uri`
        - Maximum length: `2048`
    - `type` (required):
      - Type: `string<uri>`
        - Format: `uri`
        - Maximum length: `2048`

### 408

The server did not complete the request in time. This failure is non-billable and may be retried.

This response uses [Problem Details](/reference/problem-details).

#### Headers

##### `Retry-After`

`integer` · optional

Minimum number of seconds before retrying when supplied.

- Type: `integer`
  - Minimum: `0`

##### `traceparent`

`string` · required

W3C trace context generated for this request attempt.

- Type: `string`
  - Pattern: `^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$`

##### `X-Request-Id`

`string<uuid>` · required

Unique UUIDv7 identifier for this request attempt.

- Type: `string<uuid>`
  - Format: `uuid`

#### application/problem+json

Errors follow [Problem Details](/reference/problem-details).

- Type: `ProblemDetails`
  - Component: [`ProblemDetails`](/reference/problem-details)
  - Additional properties: `forbidden`
  - Properties:
    - `available_credit_usd` (optional):
      - Type: `string`
        - Pattern: `^(?:0|[1-9]\d*)\.\d{2,6}$`
    - `code` (required):
      - Type: `string`
        - Maximum length: `80`
        - Minimum length: `1`
    - `detail` (required):
      - Type: `string`
        - Maximum length: `1000`
        - Minimum length: `1`
    - `errors` (optional):
      - Type: `object[]`
        - Maximum items: `100`
        - Items:
          - Type: `object`
            - Additional properties: `forbidden`
            - Properties:
              - `code` (required):
                - Type: `string`
                  - Maximum length: `80`
                  - Minimum length: `1`
              - `message` (required):
                - Type: `string`
                  - Maximum length: `500`
                  - Minimum length: `1`
              - `pointer` (required):
                - Type: `string`
                  - Pattern: `^\/.*`
    - `instance` (required):
      - Type: `string`
        - Pattern: `^\/.*`
    - `param` (optional):
      - Type: `string`
        - Maximum length: `160`
        - Minimum length: `1`
    - `request_id` (required):
      - Type: `string<uuid>`
        - Format: `uuid`
        - Pattern: `^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$`
    - `required_credit_usd` (optional):
      - Type: `string`
        - Pattern: `^(?:0|[1-9]\d*)\.\d{2,6}$`
    - `retryable` (required):
      - Type: `boolean`
    - `status` (required):
      - Type: `integer`
        - Maximum: `599`
        - Minimum: `400`
    - `title` (required):
      - Type: `string`
        - Maximum length: `120`
        - Minimum length: `1`
    - `top_up_url` (optional):
      - Type: `string<uri>`
        - Format: `uri`
        - Maximum length: `2048`
    - `type` (required):
      - Type: `string<uri>`
        - Format: `uri`
        - Maximum length: `2048`

### 429

The organisation request rate was exceeded. Retry after the indicated delay.

This response uses [Problem Details](/reference/problem-details).

#### Headers

##### `Retry-After`

`integer` · optional

Minimum number of seconds before retrying when supplied.

- Type: `integer`
  - Minimum: `0`

##### `traceparent`

`string` · required

W3C trace context generated for this request attempt.

- Type: `string`
  - Pattern: `^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$`

##### `X-Request-Id`

`string<uuid>` · required

Unique UUIDv7 identifier for this request attempt.

- Type: `string<uuid>`
  - Format: `uuid`

#### application/problem+json

Errors follow [Problem Details](/reference/problem-details).

- Type: `ProblemDetails`
  - Component: [`ProblemDetails`](/reference/problem-details)
  - Additional properties: `forbidden`
  - Properties:
    - `available_credit_usd` (optional):
      - Type: `string`
        - Pattern: `^(?:0|[1-9]\d*)\.\d{2,6}$`
    - `code` (required):
      - Type: `string`
        - Maximum length: `80`
        - Minimum length: `1`
    - `detail` (required):
      - Type: `string`
        - Maximum length: `1000`
        - Minimum length: `1`
    - `errors` (optional):
      - Type: `object[]`
        - Maximum items: `100`
        - Items:
          - Type: `object`
            - Additional properties: `forbidden`
            - Properties:
              - `code` (required):
                - Type: `string`
                  - Maximum length: `80`
                  - Minimum length: `1`
              - `message` (required):
                - Type: `string`
                  - Maximum length: `500`
                  - Minimum length: `1`
              - `pointer` (required):
                - Type: `string`
                  - Pattern: `^\/.*`
    - `instance` (required):
      - Type: `string`
        - Pattern: `^\/.*`
    - `param` (optional):
      - Type: `string`
        - Maximum length: `160`
        - Minimum length: `1`
    - `request_id` (required):
      - Type: `string<uuid>`
        - Format: `uuid`
        - Pattern: `^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$`
    - `required_credit_usd` (optional):
      - Type: `string`
        - Pattern: `^(?:0|[1-9]\d*)\.\d{2,6}$`
    - `retryable` (required):
      - Type: `boolean`
    - `status` (required):
      - Type: `integer`
        - Maximum: `599`
        - Minimum: `400`
    - `title` (required):
      - Type: `string`
        - Maximum length: `120`
        - Minimum length: `1`
    - `top_up_url` (optional):
      - Type: `string<uri>`
        - Format: `uri`
        - Maximum length: `2048`
    - `type` (required):
      - Type: `string<uri>`
        - Format: `uri`
        - Maximum length: `2048`

### 503

The service or durable usage settlement is temporarily unavailable. This failure is non-billable.

This response uses [Problem Details](/reference/problem-details).

#### Headers

##### `Retry-After`

`integer` · optional

Minimum number of seconds before retrying when supplied.

- Type: `integer`
  - Minimum: `0`

##### `traceparent`

`string` · required

W3C trace context generated for this request attempt.

- Type: `string`
  - Pattern: `^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$`

##### `X-Request-Id`

`string<uuid>` · required

Unique UUIDv7 identifier for this request attempt.

- Type: `string<uuid>`
  - Format: `uuid`

#### application/problem+json

Errors follow [Problem Details](/reference/problem-details).

- Type: `ProblemDetails`
  - Component: [`ProblemDetails`](/reference/problem-details)
  - Additional properties: `forbidden`
  - Properties:
    - `available_credit_usd` (optional):
      - Type: `string`
        - Pattern: `^(?:0|[1-9]\d*)\.\d{2,6}$`
    - `code` (required):
      - Type: `string`
        - Maximum length: `80`
        - Minimum length: `1`
    - `detail` (required):
      - Type: `string`
        - Maximum length: `1000`
        - Minimum length: `1`
    - `errors` (optional):
      - Type: `object[]`
        - Maximum items: `100`
        - Items:
          - Type: `object`
            - Additional properties: `forbidden`
            - Properties:
              - `code` (required):
                - Type: `string`
                  - Maximum length: `80`
                  - Minimum length: `1`
              - `message` (required):
                - Type: `string`
                  - Maximum length: `500`
                  - Minimum length: `1`
              - `pointer` (required):
                - Type: `string`
                  - Pattern: `^\/.*`
    - `instance` (required):
      - Type: `string`
        - Pattern: `^\/.*`
    - `param` (optional):
      - Type: `string`
        - Maximum length: `160`
        - Minimum length: `1`
    - `request_id` (required):
      - Type: `string<uuid>`
        - Format: `uuid`
        - Pattern: `^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$`
    - `required_credit_usd` (optional):
      - Type: `string`
        - Pattern: `^(?:0|[1-9]\d*)\.\d{2,6}$`
    - `retryable` (required):
      - Type: `boolean`
    - `status` (required):
      - Type: `integer`
        - Maximum: `599`
        - Minimum: `400`
    - `title` (required):
      - Type: `string`
        - Maximum length: `120`
        - Minimum length: `1`
    - `top_up_url` (optional):
      - Type: `string<uri>`
        - Format: `uri`
        - Maximum length: `2048`
    - `type` (required):
      - Type: `string<uri>`
        - Format: `uri`
        - Maximum length: `2048`

## Pagination

- Allows page size change: `true`
- Cursor ttl seconds: `86400`
- Has more path: `has_more`
- Items path: `data`
- Next cursor path: `next_cursor`
- Style: `keyset`

### Charging metadata

- Count path: `data`
- Meter: `company_resource`
- Model: `returned_resource`
- Resource: `company`