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

# Check flags

`POST /flags/check`

## Request body

- CheckFlagRequestBody
  - `company` object, nullable
  - `user` object, nullable

## Response `201`

Created

- object
  - `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)