---
title: "Check flags bulk"
method: POST
path: "/flags/check-bulk"
tags: ["features"]
---

# Check flags bulk

`POST /flags/check-bulk`

## Request body

- CheckFlagsBulkRequestBody
  - `contexts` CheckFlagRequestBody[], required
    - `company` object, nullable
    - `user` object, nullable

## Response `201`

Created

- object
  - `data` CheckFlagsBulkResponseData, required
    - `data` CheckFlagsResponseData[], required
      - `credit_balances` object — Lease-aware credit balances keyed by credit ID, covering every credit type the company holds a balance in
      - `flags` CheckFlagResponseData[], required
        - `company_id` string, nullable — If company keys were provided and matched a company, its ID
        - `entitlement` FeatureEntitlement
          - `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
        - `error` string, nullable — If an error occurred while checking the flag, the error message
        - `feature_allocation` integer, nullable — Deprecated: Use Entitlement.Allocation instead.
        - `feature_usage` integer, nullable — Deprecated: Use Entitlement.Usage instead.
        - `feature_usage_event` string, nullable — Deprecated: Use Entitlement.EventName instead.
        - `feature_usage_period` 'all_time' | 'current_day' | 'current_month' | 'current_week'
        - `feature_usage_reset_at` string, date-time, nullable — Deprecated: Use Entitlement.MetricResetAt instead.
        - `flag` string, required — The key used to check the flag
        - `flag_id` string, nullable — If a flag was found, its ID
        - `reason` string, required — A human-readable explanation of the result
        - `rule_id` string, nullable — If a rule was found, its ID
        - `rule_type` 'company_override' | 'company_override_usage_exceeded' | 'default' | 'global_override' | 'plan_entitlement' | 'plan_entitlement_usage_exceeded' | 'standard'
        - `user_id` string, nullable — If user keys were provided and matched a user, its ID
        - `value` boolean, required — A boolean flag check result; for feature entitlements, this represents whether further consumption of the feature is permitted
      - `plan` DatastreamCompanyPlan
        - `id` string, required
        - `name` string, required
        - `trial_end_date` string, date-time, nullable
        - `trial_status` 'active' | 'converted' | 'expired'
  - `params` object, required — Input parameters

## Other responses

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

---

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