---
title: "Check flag"
method: POST
path: "/flags/{key}/check"
tags: ["features"]
---

# Check flag

`POST /flags/{key}/check`

## Path parameters

- `key` string, required

## Request body

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

## Response `200`

OK

- object
  - `data` 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
  - `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/versions/873fb318b08a/schema)