---
title: "List companies"
method: GET
path: "/companies"
tags: ["companies"]
---

# List companies

`GET /companies`

## Query parameters

- `credit_type_ids` string[] — Filter companies by one or more credit type IDs (each ID starts with bcrd_)
- `has_scheduled_downgrade` boolean — Filter companies that have a pending scheduled downgrade
- `ids` string[] — Filter companies by multiple company IDs (starts with comp_)
- `monetized_subscriptions` boolean — Filter companies that have monetized subscriptions
- `plan_id` string — Filter companies by plan ID (starts with plan_)
- `plan_ids` string[] — Filter companies by one or more plan IDs (each ID starts with plan_)
- `plan_version_id` string — Filter companies by plan version ID (starts with plvr_)
- `plan_version_ids` string[] — Filter companies by one or more plan version IDs (each ID starts with plvr_). Takes precedence over plan_version_id when set.
- `plan_version_unpublished` boolean — Filter companies assigned to a plan version that is no longer published, meaning the plan has since moved on to a newer version
- `q` string — Search for companies by name, keys or string traits
- `sort_order_column` string — Column to sort by (e.g. name, created_at, last_seen_at)
- `sort_order_direction` 'asc' | 'desc'
- `subscription_statuses` SubscriptionStatus[] — Filter companies by one or more subscription statuses
- `subscription_types` SubscriptionType[] — Filter companies by one or more subscription types
- `with_entitlement_for` string — Filter companies that have an entitlement (plan entitlement or company override) for the specified feature ID
- `without_feature_override_for` string — Filter out companies that already have a company override for the specified feature ID
- `without_plan` boolean — Filter out companies that have a plan
- `without_subscription` boolean — Filter out companies that have a subscription
- `with_subscription` boolean — Filter companies that have a subscription
- `limit` integer — Page limit (default 100)
- `offset` integer — Page offset (default 0)

## Response `200`

OK

- object
  - `data` CompanyDetailResponseData[], required
    - `add_ons` CompanyPlanWithBillingSubView[], required
      - `added_on` string, date-time, nullable
      - `billing_product_external_id` string, nullable
      - `billing_product_id` string, nullable
      - `description` string, nullable
      - `id` string, required
      - `image_url` string, nullable
      - `included_credit_grants` CompanyPlanCreditGrantView[], required
        - `billing_credit_auto_topup_amount` integer, nullable
        - `billing_credit_auto_topup_amount_type` string, nullable
        - `billing_credit_auto_topup_availability` 'off' | 'automatic' | 'user_controlled'
        - `billing_credit_auto_topup_enabled` boolean, required
        - `billing_credit_auto_topup_expiry_type` 'duration' | 'end_of_billing_period' | 'end_of_next_billing_period' | 'end_of_trial' | 'no_expiry'
        - `billing_credit_auto_topup_expiry_unit` 'billing_periods' | 'days'
        - `billing_credit_auto_topup_expiry_unit_count` integer, nullable
        - `billing_credit_auto_topup_self_service` boolean, required
        - `billing_credit_auto_topup_threshold_credits` integer, nullable
        - `billing_credit_auto_topup_threshold_percent` integer, nullable
        - `billing_credit_can_buy_bundles` boolean, required
        - `company_auto_topup_amount` integer, nullable
        - `company_auto_topup_enabled` boolean, nullable
        - `company_auto_topup_threshold_credits` integer, nullable
        - `company_credit_amount` integer, required
        - `created_at` string, date-time, required
        - `credit` BillingCreditView
          - `account_id` string, required
          - `burn_strategy` 'expiration_priority' | 'first_in_first_out' | 'last_in_first_out' | 'plan_first_then_credit_bundles_first_in_first_out', required
          - `cost_editable` boolean, required
          - `created_at` string, date-time, required
          - `currency_prices` CreditCurrencyPrice[], required
            - `currency` string, required
            - `price` BillingPriceView
              - …
          - `default_expiry_unit` 'billing_periods' | 'days', required
          - `default_expiry_unit_count` integer, nullable
          - `default_rollover_policy` 'expire' | 'none' | 'rollover', required
          - `description` string, required
          - `environment_id` string, required
          - `icon` string, nullable
          - `id` string, required
          - `ledger_authority` 'schematic_authoritative' | 'external_mirror' | 'external_rated', required
          - `name` string, required
          - `plural_name` string, nullable
          - `price` BillingPriceView
            - `billing_scheme` 'per_unit' | 'tiered', required
            - `created_at` string, date-time, required
            - `currency` string, required
            - `id` string, required
            - `interval` 'day' | 'month' | 'one-time' | 'year', required
            - `interval_count` integer, required
            - `is_active` boolean, required
            - `meter_event_name` string, nullable
            - `meter_event_payload_key` string, nullable
            - `meter_id` string, nullable
            - `nickname` string, nullable
            - `package_size` integer, required
            - `price` integer, required
            - `price_decimal` string, nullable
            - `price_external_id` string, required
            - `price_id` string, required
            - `price_tier` BillingProductPriceTierResponseData[], required
              - …
            - `product_external_id` string, required
            - `product_id` string, required
            - `product_name` string, required
            - `provider_type` 'metronome' | 'orb' | 'schematic' | 'stripe', required
            - `tiers_mode` 'graduated' | 'volume'
            - `updated_at` string, date-time, required
            - `usage_type` 'licensed' | 'metered', required
          - `price_per_unit` integer, nullable
          - `price_per_unit_decimal` string, nullable
          - `product` BillingProductRecordResponseData
            - `account_id` string, required
            - `created_at` string, date-time, required
            - `environment_id` string, required
            - `external_id` string, required
            - `id` string, required
            - `is_active` boolean, required
            - `name` string, required
            - `provider_type` 'metronome' | 'orb' | 'schematic' | 'stripe', required
            - `updated_at` string, date-time, required
          - `singular_name` string, nullable
          - `updated_at` string, date-time, required
        - `credit_amount` integer, required
        - `credit_description` string, required — Deprecated field, will be removed in the future. Use Credit.Description instead.
        - `credit_icon` string, nullable — Deprecated field, will be removed in the future. Use Credit.Icon instead.
        - `credit_id` string, required
        - `credit_name` string, required — Deprecated field, will be removed in the future. Use Credit.Name instead.
        - `expiry_type` 'duration' | 'end_of_billing_period' | 'end_of_next_billing_period' | 'end_of_trial' | 'no_expiry'
        - `expiry_unit` 'billing_periods' | 'days'
        - `expiry_unit_count` integer, nullable
        - `id` string, required
        - `license_id` string, nullable
        - `plan` GenericPreviewObject
          - `description` string, nullable
          - `id` string, required
          - `image_url` string, nullable
          - `name` string, required
        - `plan_id` string, required
        - `plan_version_id` string, nullable
        - `plural_name` string, nullable — Deprecated field, will be removed in the future. Use Credit.PluralName instead.
        - `reset_cadence` 'daily' | 'every_6_months' | 'monthly' | 'quarterly' | 'weekly' | 'yearly'
        - `reset_start` 'billing_period' | 'first_of_month'
        - `reset_type` 'no_reset' | 'plan_period', required
        - `rollover_percentage` integer, required
        - `scaling` 'fixed' | 'per_license', required
        - `singular_name` string, nullable — Deprecated field, will be removed in the future. Use Credit.SingularName instead.
        - `updated_at` string, date-time, required
      - `name` string, required
      - `plan_period` string, nullable
      - `plan_price` integer, nullable
      - `plan_version_id` string, nullable
    - `billing_credit_balances` object, nullable
    - `billing_subscription` BillingSubscriptionView
      - `application_id` string, nullable
      - `cancel_at` integer, nullable
      - `cancel_at_period_end` boolean, required
      - `company_id` string, nullable
      - `created_at` string, date-time, required
      - `currency` string, required
      - `customer_external_id` string, required
      - `default_payment_method_id` string, nullable
      - `discounts` BillingSubscriptionDiscountView[], required
        - `amount_off` integer, nullable
        - `coupon_id` string, required
        - `coupon_name` string, required
        - `currency` string, nullable
        - `customer_facing_code` string, nullable
        - `discount_external_id` string, required
        - `duration` string, required
        - `duration_in_months` integer, nullable
        - `ended_at` string, date-time, nullable
        - `is_active` boolean, required
        - `percent_off` number, double, nullable
        - `promo_code_external_id` string, nullable
        - `started_at` string, date-time, required
        - `subscription_external_id` string, required
      - `expired_at` string, date-time, nullable
      - `id` string, required
      - `interval` string, required
      - `latest_invoice` InvoiceResponseData
        - `amount_due` integer, required
        - `amount_paid` integer, required
        - `amount_remaining` integer, required
        - `collection_method` string, required
        - `company_id` string, nullable
        - `created_at` string, date-time, required
        - `currency` string, required
        - `customer_external_id` string, required
        - `due_date` string, date-time, nullable
        - `ending_balance` integer, required
        - `environment_id` string, required
        - `external_id` string, nullable
        - `id` string, required
        - `payment_method_external_id` string, nullable
        - `provider_type` 'metronome' | 'orb' | 'schematic' | 'stripe', required
        - `starting_balance` integer, required
        - `status` 'draft' | 'open' | 'paid' | 'uncollectible' | 'void'
        - `subscription_external_id` string, nullable
        - `subtotal` integer, required
        - `updated_at` string, date-time, required
        - `url` string, nullable
      - `metadata` object
      - `payment_method` PaymentMethodResponseData
        - `account_last4` string, nullable
        - `account_name` string, nullable
        - `bank_name` string, nullable
        - `billing_email` string, nullable
        - `billing_name` string, nullable
        - `card_brand` string, nullable
        - `card_exp_month` integer, nullable
        - `card_exp_year` integer, nullable
        - `card_last4` string, nullable
        - `company_id` string, nullable
        - `created_at` string, date-time, required
        - `customer_external_id` string, required
        - `environment_id` string, required
        - `external_id` string, required
        - `id` string, required
        - `payment_method_type` string, required
        - `provider_type` 'metronome' | 'orb' | 'schematic' | 'stripe', required
        - `updated_at` string, date-time, required
      - `period_end` integer, required
      - `period_start` integer, required
      - `products` BillingProductForSubscriptionResponseData[], required
        - `billing_scheme` 'per_unit' | 'tiered', required
        - `billing_threshold` integer, nullable
        - `created_at` string, date-time, required
        - `currency` string, required
        - `environment_id` string, required
        - `external_id` string, required
        - `id` string, required
        - `interval` string, required
        - `interval_count` integer, nullable
        - `meter_id` string, nullable
        - `name` string, required
        - `package_size` integer, required
        - `price` integer, required
        - `price_decimal` string, nullable
        - `price_external_id` string, required
        - `price_id` string, required
        - `price_tier` BillingProductPriceTierResponseData[], required
          - `flat_amount` integer, nullable
          - `per_unit_price` integer, nullable
          - `per_unit_price_decimal` string, nullable
          - `up_to` integer, nullable
        - `provider_type` 'metronome' | 'orb' | 'schematic' | 'stripe', required
        - `quantity` number, double, required
        - `subscription_id` string, required
        - `subscription_item_external_id` string, nullable
        - `updated_at` string, date-time, required
        - `usage_type` 'licensed' | 'metered', required
      - `provider_type` 'metronome' | 'orb' | 'schematic' | 'stripe', required
      - `status` string, required
      - `subscription_external_id` string, required
      - `total_price` integer, required
      - `trial_end` integer, nullable
      - `trial_end_setting` 'cancel' | 'subscribe'
    - `billing_subscriptions` BillingSubscriptionView[], required
      - `application_id` string, nullable
      - `cancel_at` integer, nullable
      - `cancel_at_period_end` boolean, required
      - `company_id` string, nullable
      - `created_at` string, date-time, required
      - `currency` string, required
      - `customer_external_id` string, required
      - `default_payment_method_id` string, nullable
      - `discounts` BillingSubscriptionDiscountView[], required
        - `amount_off` integer, nullable
        - `coupon_id` string, required
        - `coupon_name` string, required
        - `currency` string, nullable
        - `customer_facing_code` string, nullable
        - `discount_external_id` string, required
        - `duration` string, required
        - `duration_in_months` integer, nullable
        - `ended_at` string, date-time, nullable
        - `is_active` boolean, required
        - `percent_off` number, double, nullable
        - `promo_code_external_id` string, nullable
        - `started_at` string, date-time, required
        - `subscription_external_id` string, required
      - `expired_at` string, date-time, nullable
      - `id` string, required
      - `interval` string, required
      - `latest_invoice` InvoiceResponseData
        - `amount_due` integer, required
        - `amount_paid` integer, required
        - `amount_remaining` integer, required
        - `collection_method` string, required
        - `company_id` string, nullable
        - `created_at` string, date-time, required
        - `currency` string, required
        - `customer_external_id` string, required
        - `due_date` string, date-time, nullable
        - `ending_balance` integer, required
        - `environment_id` string, required
        - `external_id` string, nullable
        - `id` string, required
        - `payment_method_external_id` string, nullable
        - `provider_type` 'metronome' | 'orb' | 'schematic' | 'stripe', required
        - `starting_balance` integer, required
        - `status` 'draft' | 'open' | 'paid' | 'uncollectible' | 'void'
        - `subscription_external_id` string, nullable
        - `subtotal` integer, required
        - `updated_at` string, date-time, required
        - `url` string, nullable
      - `metadata` object
      - `payment_method` PaymentMethodResponseData
        - `account_last4` string, nullable
        - `account_name` string, nullable
        - `bank_name` string, nullable
        - `billing_email` string, nullable
        - `billing_name` string, nullable
        - `card_brand` string, nullable
        - `card_exp_month` integer, nullable
        - `card_exp_year` integer, nullable
        - `card_last4` string, nullable
        - `company_id` string, nullable
        - `created_at` string, date-time, required
        - `customer_external_id` string, required
        - `environment_id` string, required
        - `external_id` string, required
        - `id` string, required
        - `payment_method_type` string, required
        - `provider_type` 'metronome' | 'orb' | 'schematic' | 'stripe', required
        - `updated_at` string, date-time, required
      - `period_end` integer, required
      - `period_start` integer, required
      - `products` BillingProductForSubscriptionResponseData[], required
        - `billing_scheme` 'per_unit' | 'tiered', required
        - `billing_threshold` integer, nullable
        - `created_at` string, date-time, required
        - `currency` string, required
        - `environment_id` string, required
        - `external_id` string, required
        - `id` string, required
        - `interval` string, required
        - `interval_count` integer, nullable
        - `meter_id` string, nullable
        - `name` string, required
        - `package_size` integer, required
        - `price` integer, required
        - `price_decimal` string, nullable
        - `price_external_id` string, required
        - `price_id` string, required
        - `price_tier` BillingProductPriceTierResponseData[], required
          - `flat_amount` integer, nullable
          - `per_unit_price` integer, nullable
          - `per_unit_price_decimal` string, nullable
          - `up_to` integer, nullable
        - `provider_type` 'metronome' | 'orb' | 'schematic' | 'stripe', required
        - `quantity` number, double, required
        - `subscription_id` string, required
        - `subscription_item_external_id` string, nullable
        - `updated_at` string, date-time, required
        - `usage_type` 'licensed' | 'metered', required
      - `provider_type` 'metronome' | 'orb' | 'schematic' | 'stripe', required
      - `status` string, required
      - `subscription_external_id` string, required
      - `total_price` integer, required
      - `trial_end` integer, nullable
      - `trial_end_setting` 'cancel' | 'subscribe'
    - `created_at` string, date-time, required
    - `custom_plan_billings` CustomPlanBillingResponseData[], required
      - `activation_strategy` 'on_payment' | 'on_publish', required
      - `billing_cycle_anchor` string, date-time, nullable — The billing period renewal date pinned when the subscription started, when one was set. When no invoice exists yet, the first invoice is raised on this date.
      - `company_id` string, required
      - `created_at` string, date-time, required
      - `days_until_due` integer, required
      - `external_invoice_id` string, nullable
      - `id` string, required
      - `paid_at` string, date-time, nullable
      - `plan_billing_source` 'custom_plan' | 'manage_plan', required
      - `plan_id` string, required
      - `prorate_first_period` boolean, nullable — Whether the shortened period the renewal date created was billed pro rata when the subscription started. False means that period is free and the first invoice is the one raised on the renewal date.
      - `published_at` string, date-time, nullable
      - `send_invoice` boolean, required
      - `status` 'active' | 'expired' | 'paid' | 'pending', required
      - `stripe_invoice_url` string, nullable
      - `updated_at` string, date-time, required
    - `default_payment_method` PaymentMethodResponseData
      - `account_last4` string, nullable
      - `account_name` string, nullable
      - `bank_name` string, nullable
      - `billing_email` string, nullable
      - `billing_name` string, nullable
      - `card_brand` string, nullable
      - `card_exp_month` integer, nullable
      - `card_exp_year` integer, nullable
      - `card_last4` string, nullable
      - `company_id` string, nullable
      - `created_at` string, date-time, required
      - `customer_external_id` string, required
      - `environment_id` string, required
      - `external_id` string, required
      - `id` string, required
      - `payment_method_type` string, required
      - `provider_type` 'metronome' | 'orb' | 'schematic' | 'stripe', required
      - `updated_at` string, date-time, required
    - `entitlements` FeatureEntitlement[], required
      - `allocation` integer, nullable — If the company has a numeric entitlement for this feature, the allocated amount
      - `consumption_rate` number, double, nullable — If the company has a credit-based entitlement for this feature, the credit cost per unit of usage
      - `credit_id` string, nullable — If the company has a credit-based entitlement for this feature, the ID of the credit
      - `credit_remaining` number, double, nullable — If the company has a credit-based entitlement for this feature, the credit available to fund new consumption or a new lease hold — open lease holds are excluded. Clients that hold a lease should gate on this plus their own unspent hold; clients with no lease awareness should use credit_settled instead
      - `credit_reserved` number, double, nullable — If the company has a credit-based entitlement for this feature, the unspent amount held by an open credit lease. Returns to credit_remaining when the lease is released
      - `credit_settled` number, double, nullable — If the company has a credit-based entitlement for this feature, the balance net of actual consumption, unaffected by open lease holds (credit_remaining plus credit_reserved). The number to display to end users
      - `credit_total` number, double, nullable — If the company has a credit-based entitlement for this feature, the total credit amount
      - `credit_used` number, double, nullable — If the company has a credit-based entitlement for this feature, the amount of credit used
      - `event_name` string, nullable — If the feature is event-based, the name of the event tracked for usage
      - `event_subtype` string, nullable — For event-based or credit-metered feature entitlements, the event subtype whose usage is tracked
      - `feature_id` string, required — The ID of the feature
      - `feature_key` string, required — The key of the flag associated with the feature
      - `metric_period` 'all_time' | 'current_day' | 'current_month' | 'current_week'
      - `metric_reset_at` string, date-time, nullable — For event-based feature entitlements, when the usage period will reset
      - `month_reset` 'billing_cycle' | 'first_of_month'
      - `soft_limit` integer, nullable — For usage-based pricing, the soft limit for overage charges or the next tier boundary
      - `usage` integer, nullable — If the company has a numeric entitlement for this feature, the current usage amount
      - `value_type` 'boolean' | 'credit' | 'numeric' | 'trait' | 'unknown' | 'unlimited', required
      - `warning_tiers` WarningTier[] — Customer-defined usage warning thresholds configured on this entitlement
        - `key` string, required — A customer-defined identifier for the warning tier
        - `value` integer, required — The warning threshold, in the entitlement's usage units
    - `entity_traits` EntityTraitDetailResponseData[], required
      - `created_at` string, date-time, required
      - `definition` EntityTraitDefinitionResponseData
        - `created_at` string, date-time, required
        - `display_name` string, required
        - `entity_type` 'company' | 'user', required
        - `hierarchy` string[], required
        - `id` string, required
        - `trait_type` 'boolean' | 'currency' | 'date' | 'number' | 'string' | 'url', required
        - `updated_at` string, date-time, required
      - `definition_id` string, required
      - `environment_id` string, required
      - `id` string, required
      - `updated_at` string, date-time, required
      - `value` string, required
    - `environment_id` string, required
    - `id` string, required
    - `keys` EntityKeyDetailResponseData[], required
      - `created_at` string, date-time, required
      - `definition` EntityKeyDefinitionResponseData
        - `created_at` string, date-time, required
        - `entity_type` 'company' | 'user', required
        - `id` string, required
        - `key` string, required
        - `updated_at` string, date-time, required
      - `definition_id` string, required
      - `entity_id` string, required
      - `entity_type` 'company' | 'user', required
      - `environment_id` string, required
      - `id` string, required
      - `key` string, required
      - `updated_at` string, date-time, required
      - `value` string, required
    - `last_seen_at` string, date-time, nullable
    - `logo_url` string, nullable
    - `metrics` CompanyEventPeriodMetricsResponseData[], required
      - `account_id` string, required
      - `captured_at_max` string, date-time, required
      - `captured_at_min` string, date-time, required
      - `company_id` string, required
      - `created_at` string, date-time, required
      - `environment_id` string, required
      - `event_subtype` string, required
      - `month_reset` 'billing_cycle' | 'first_of_month', required
      - `period` 'all_time' | 'current_day' | 'current_month' | 'current_week', required
      - `valid_until` string, date-time, nullable
      - `value` integer, required
    - `name` string, required
    - `payment_methods` PaymentMethodResponseData[], required
      - `account_last4` string, nullable
      - `account_name` string, nullable
      - `bank_name` string, nullable
      - `billing_email` string, nullable
      - `billing_name` string, nullable
      - `card_brand` string, nullable
      - `card_exp_month` integer, nullable
      - `card_exp_year` integer, nullable
      - `card_last4` string, nullable
      - `company_id` string, nullable
      - `created_at` string, date-time, required
      - `customer_external_id` string, required
      - `environment_id` string, required
      - `external_id` string, required
      - `id` string, required
      - `payment_method_type` string, required
      - `provider_type` 'metronome' | 'orb' | 'schematic' | 'stripe', required
      - `updated_at` string, date-time, required
    - `pending_migration` PendingMigrationResponseData
      - `migration_id` string, required
      - `scheduled_for` string, date-time, nullable
      - `to_plan_id` string, required
      - `to_plan_name` string, required
      - `to_plan_version_id` string, required
      - `to_plan_version_number` integer, nullable
    - `plan` CompanyPlanWithBillingSubView
      - `added_on` string, date-time, nullable
      - `billing_product_external_id` string, nullable
      - `billing_product_id` string, nullable
      - `description` string, nullable
      - `id` string, required
      - `image_url` string, nullable
      - `included_credit_grants` CompanyPlanCreditGrantView[], required
        - `billing_credit_auto_topup_amount` integer, nullable
        - `billing_credit_auto_topup_amount_type` string, nullable
        - `billing_credit_auto_topup_availability` 'off' | 'automatic' | 'user_controlled'
        - `billing_credit_auto_topup_enabled` boolean, required
        - `billing_credit_auto_topup_expiry_type` 'duration' | 'end_of_billing_period' | 'end_of_next_billing_period' | 'end_of_trial' | 'no_expiry'
        - `billing_credit_auto_topup_expiry_unit` 'billing_periods' | 'days'
        - `billing_credit_auto_topup_expiry_unit_count` integer, nullable
        - `billing_credit_auto_topup_self_service` boolean, required
        - `billing_credit_auto_topup_threshold_credits` integer, nullable
        - `billing_credit_auto_topup_threshold_percent` integer, nullable
        - `billing_credit_can_buy_bundles` boolean, required
        - `company_auto_topup_amount` integer, nullable
        - `company_auto_topup_enabled` boolean, nullable
        - `company_auto_topup_threshold_credits` integer, nullable
        - `company_credit_amount` integer, required
        - `created_at` string, date-time, required
        - `credit` BillingCreditView
          - `account_id` string, required
          - `burn_strategy` 'expiration_priority' | 'first_in_first_out' | 'last_in_first_out' | 'plan_first_then_credit_bundles_first_in_first_out', required
          - `cost_editable` boolean, required
          - `created_at` string, date-time, required
          - `currency_prices` CreditCurrencyPrice[], required
            - `currency` string, required
            - `price` BillingPriceView
              - …
          - `default_expiry_unit` 'billing_periods' | 'days', required
          - `default_expiry_unit_count` integer, nullable
          - `default_rollover_policy` 'expire' | 'none' | 'rollover', required
          - `description` string, required
          - `environment_id` string, required
          - `icon` string, nullable
          - `id` string, required
          - `ledger_authority` 'schematic_authoritative' | 'external_mirror' | 'external_rated', required
          - `name` string, required
          - `plural_name` string, nullable
          - `price` BillingPriceView
            - `billing_scheme` 'per_unit' | 'tiered', required
            - `created_at` string, date-time, required
            - `currency` string, required
            - `id` string, required
            - `interval` 'day' | 'month' | 'one-time' | 'year', required
            - `interval_count` integer, required
            - `is_active` boolean, required
            - `meter_event_name` string, nullable
            - `meter_event_payload_key` string, nullable
            - `meter_id` string, nullable
            - `nickname` string, nullable
            - `package_size` integer, required
            - `price` integer, required
            - `price_decimal` string, nullable
            - `price_external_id` string, required
            - `price_id` string, required
            - `price_tier` BillingProductPriceTierResponseData[], required
              - …
            - `product_external_id` string, required
            - `product_id` string, required
            - `product_name` string, required
            - `provider_type` 'metronome' | 'orb' | 'schematic' | 'stripe', required
            - `tiers_mode` 'graduated' | 'volume'
            - `updated_at` string, date-time, required
            - `usage_type` 'licensed' | 'metered', required
          - `price_per_unit` integer, nullable
          - `price_per_unit_decimal` string, nullable
          - `product` BillingProductRecordResponseData
            - `account_id` string, required
            - `created_at` string, date-time, required
            - `environment_id` string, required
            - `external_id` string, required
            - `id` string, required
            - `is_active` boolean, required
            - `name` string, required
            - `provider_type` 'metronome' | 'orb' | 'schematic' | 'stripe', required
            - `updated_at` string, date-time, required
          - `singular_name` string, nullable
          - `updated_at` string, date-time, required
        - `credit_amount` integer, required
        - `credit_description` string, required — Deprecated field, will be removed in the future. Use Credit.Description instead.
        - `credit_icon` string, nullable — Deprecated field, will be removed in the future. Use Credit.Icon instead.
        - `credit_id` string, required
        - `credit_name` string, required — Deprecated field, will be removed in the future. Use Credit.Name instead.
        - `expiry_type` 'duration' | 'end_of_billing_period' | 'end_of_next_billing_period' | 'end_of_trial' | 'no_expiry'
        - `expiry_unit` 'billing_periods' | 'days'
        - `expiry_unit_count` integer, nullable
        - `id` string, required
        - `license_id` string, nullable
        - `plan` GenericPreviewObject
          - `description` string, nullable
          - `id` string, required
          - `image_url` string, nullable
          - `name` string, required
        - `plan_id` string, required
        - `plan_version_id` string, nullable
        - `plural_name` string, nullable — Deprecated field, will be removed in the future. Use Credit.PluralName instead.
        - `reset_cadence` 'daily' | 'every_6_months' | 'monthly' | 'quarterly' | 'weekly' | 'yearly'
        - `reset_start` 'billing_period' | 'first_of_month'
        - `reset_type` 'no_reset' | 'plan_period', required
        - `rollover_percentage` integer, required
        - `scaling` 'fixed' | 'per_license', required
        - `singular_name` string, nullable — Deprecated field, will be removed in the future. Use Credit.SingularName instead.
        - `updated_at` string, date-time, required
      - `name` string, required
      - `plan_period` string, nullable
      - `plan_price` integer, nullable
      - `plan_version_id` string, nullable
    - `plans` GenericPreviewObject[], required
      - `description` string, nullable
      - `id` string, required
      - `image_url` string, nullable
      - `name` string, required
    - `rules` Rule[], required
      - `account_id` string, required
      - `condition_groups` ConditionGroup[], required
        - `conditions` Condition[], required
          - `account_id` string, required
          - `comparison_trait_definition` TraitDefinition
            - `comparable_type` 'bool' | 'date' | 'int' | 'string', required
            - `entity_type` 'company' | 'user', required
            - `id` string, required
          - `condition_type` 'base_plan' | 'billing_product' | 'company' | 'credit' | 'metric' | 'plan' | 'plan_version' | 'trait' | 'user', required
          - `consumption_rate` number, double, nullable
          - `credit_id` string, nullable
          - `environment_id` string, required
          - `event_subtype` string, nullable
          - `id` string, required
          - `metric_period` 'all_time' | 'current_day' | 'current_month' | 'current_week'
          - `metric_period_month_reset` 'billing_cycle' | 'first_of_month'
          - `metric_value` integer, nullable
          - `operator` 'eq' | 'gt' | 'gte' | 'is_empty' | 'lt' | 'lte' | 'not_empty' | 'ne', required
          - `resource_ids` string[], required
          - `trait_definition` TraitDefinition
            - `comparable_type` 'bool' | 'date' | 'int' | 'string', required
            - `entity_type` 'company' | 'user', required
            - `id` string, required
          - `trait_value` string, required
      - `conditions` Condition[], required
        - `account_id` string, required
        - `comparison_trait_definition` TraitDefinition
          - `comparable_type` 'bool' | 'date' | 'int' | 'string', required
          - `entity_type` 'company' | 'user', required
          - `id` string, required
        - `condition_type` 'base_plan' | 'billing_product' | 'company' | 'credit' | 'metric' | 'plan' | 'plan_version' | 'trait' | 'user', required
        - `consumption_rate` number, double, nullable
        - `credit_id` string, nullable
        - `environment_id` string, required
        - `event_subtype` string, nullable
        - `id` string, required
        - `metric_period` 'all_time' | 'current_day' | 'current_month' | 'current_week'
        - `metric_period_month_reset` 'billing_cycle' | 'first_of_month'
        - `metric_value` integer, nullable
        - `operator` 'eq' | 'gt' | 'gte' | 'is_empty' | 'lt' | 'lte' | 'not_empty' | 'ne', required
        - `resource_ids` string[], required
        - `trait_definition` TraitDefinition
          - `comparable_type` 'bool' | 'date' | 'int' | 'string', required
          - `entity_type` 'company' | 'user', required
          - `id` string, required
        - `trait_value` string, required
      - `environment_id` string, required
      - `flag_id` string, nullable
      - `id` string, required
      - `name` string, required
      - `priority` integer, required
      - `rule_type` 'company_override' | 'company_override_usage_exceeded' | 'default' | 'global_override' | 'plan_entitlement' | 'plan_entitlement_usage_exceeded' | 'standard', required
      - `value` boolean, required
    - `scheduled_downgrade` ScheduledDowngradeResponseData
      - `currency` string, required
      - `effective_after` string, date-time, required
      - `from_plan_id` string, required
      - `from_plan_name` string, required
      - `from_subscription_price` integer, required
      - `id` string, required
      - `interval` string, required
      - `scheduled_interval` string, nullable
      - `scheduled_price` integer, nullable
      - `to_plan_id` string, required
      - `to_plan_name` string, required
    - `traits` object — A map of trait names to trait values
    - `updated_at` string, date-time, required
    - `user_count` integer, required
  - `params` object, required — Input parameters
    - `credit_type_ids` string[] — Filter companies by one or more credit type IDs (each ID starts with bcrd_)
    - `has_scheduled_downgrade` boolean — Filter companies that have a pending scheduled downgrade
    - `ids` string[] — Filter companies by multiple company IDs (starts with comp_)
    - `limit` integer — Page limit (default 100)
    - `monetized_subscriptions` boolean — Filter companies that have monetized subscriptions
    - `offset` integer — Page offset (default 0)
    - `plan_id` string — Filter companies by plan ID (starts with plan_)
    - `plan_ids` string[] — Filter companies by one or more plan IDs (each ID starts with plan_)
    - `plan_version_id` string — Filter companies by plan version ID (starts with plvr_)
    - `plan_version_ids` string[] — Filter companies by one or more plan version IDs (each ID starts with plvr_). Takes precedence over plan_version_id when set.
    - `plan_version_unpublished` boolean — Filter companies assigned to a plan version that is no longer published, meaning the plan has since moved on to a newer version
    - `q` string — Search for companies by name, keys or string traits
    - `sort_order_column` string — Column to sort by (e.g. name, created_at, last_seen_at)
    - `sort_order_direction` 'asc' | 'desc'
    - `subscription_statuses` SubscriptionStatus[] — Filter companies by one or more subscription statuses
    - `subscription_types` SubscriptionType[] — Filter companies by one or more subscription types
    - `with_entitlement_for` string — Filter companies that have an entitlement (plan entitlement or company override) for the specified feature ID
    - `with_subscription` boolean — Filter companies that have a subscription
    - `without_feature_override_for` string — Filter out companies that already have a company override for the specified feature ID
    - `without_plan` boolean — Filter out companies that have a plan
    - `without_subscription` boolean — Filter out companies that have a subscription

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not found
- `500` — Server error

## Changes

> 125 revisions in range; 61 could not be searched.

- **2026-07-16** `ae246bb663d6` — 1 info
  - added the optional property `data/items/entitlements/items/warning_tiers` to the response with the `200` status
- **2026-07-15** `3baa54bf8b3f` — 2 warning
  - for the `query` request parameter `limit`, the max was set to `250.00`
  - for the `query` request parameter `limit`, the min was set to `0.00`
- **2026-07-13** `8dc48f048ad5` — 4 info
  - added the required property `data/items/billing_subscription/latest_invoice/ending_balance` to the response with the `200` status
  - added the required property `data/items/billing_subscription/latest_invoice/starting_balance` to the response with the `200` status
  - added the required property `data/items/billing_subscriptions/items/latest_invoice/ending_balance` to the response with the `200` status
  - added the required property `data/items/billing_subscriptions/items/latest_invoice/starting_balance` to the response with the `200` status
- …earlier changes not shown

[Full history](https://skmtc.dev/schematichq/apis/schematic-api/changes/companies/get.md)

---

[API](https://skmtc.dev/schematichq/apis/schematic-api.md) · [All operations](https://skmtc.dev/schematichq/apis/schematic-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/schematichq/schematic-api/revisions/0b238e148fa1/schema)