--- title: "Get subscription" method: GET path: "/api/v1/subscription" tags: ["Subscription"] --- # Get subscription `GET /api/v1/subscription` Get the subscription ## Response `200` The request has succeeded. - CloudSubscription — The subscription information. - `currentPeriodEnd` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `currentPeriodStart` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `hasStripeSubscription` boolean - `items` CloudSubscriptionItem[], required - `description` string - `entitlement` union — Entitlement templates are used to define the entitlements of a plan. Features are omitted from the entitlement template, as they are defined in the rate card. - object — Metered entitlements are useful for many different use cases, from setting up usage based access to implementing complex credit systems. Access is determined based on feature usage using a balance calculation (the "usage allowance" provided by the issued grants is "burnt down" by the usage). - `activeFrom` string, date-time, required — The cadence start of the resource. - `activeTo` string, date-time — The cadence end of the resource. - `annotations` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `currentUsagePeriod` Period, required — A period with a start and end time. - `from` string, date-time, required — Period start time. - `to` string, date-time, required — Period end time. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `featureId` string, required — The feature the subject is entitled to use. - `featureKey` string, required — The feature the subject is entitled to use. - `id` string, required — Readonly unique ULID identifier. - `isSoftLimit` boolean — If softLimit=true the subject can use the feature even if the entitlement is exhausted, hasAccess will always be true. - `isUnlimited` boolean — Deprecated, ignored by the backend. Please use isSoftLimit instead; this field will be removed in the future. - `issueAfterReset` number, double — You can grant usage automatically alongside the entitlement, the example scenario would be creating a starting balance. If an amount is specified here, a grant will be created alongside the entitlement with the specified amount. That grant will have it's rollover settings configured in a way that after each reset operation, the balance will return the original amount specified here. Manually creating such a grant would mean having the "amount", "minRolloverAmount", and "maxRolloverAmount" fields all be the same. - `issueAfterResetPriority` integer — Defines the grant priority for the default grant. - `lastReset` string, date-time, required — The time the last reset happened. - `measureUsageFrom` string, date-time, required — The time from which usage is measured. If not specified on creation, defaults to entitlement creation time. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `preserveOverageAtReset` boolean — If true, the overage is preserved at reset. If false, the usage is reset to 0. - `subjectKey` string, required — The identifier key unique to the subject. NOTE: Subjects are being deprecated, please use the new customer APIs. - `type` 'metered', required - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `usagePeriod` RecurringPeriod, required — Recurring period with an interval and an anchor. - `anchor` string, date-time, required — A date-time anchor to base the recurring period on. - `interval` union, required — Period duration for the recurrence - string - 'DAY' | 'WEEK' | 'MONTH' | 'YEAR' — The unit of time for the interval. One of: `day`, `week`, `month`, or `year`. - `intervalISO` string, duration, required — The unit of time for the interval in ISO8601 format. - object — A static entitlement. - `activeFrom` string, date-time, required — The cadence start of the resource. - `activeTo` string, date-time — The cadence end of the resource. - `annotations` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user. - `config` string, json, required — The JSON parsable config of the entitlement. This value is also returned when checking entitlement access and it is useful for configuring fine-grained access settings to the feature, implemented in your own system. Has to be an object. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `currentUsagePeriod` Period — A period with a start and end time. - `from` string, date-time, required — Period start time. - `to` string, date-time, required — Period end time. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `featureId` string, required — The feature the subject is entitled to use. - `featureKey` string, required — The feature the subject is entitled to use. - `id` string, required — Readonly unique ULID identifier. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `subjectKey` string, required — The identifier key unique to the subject. NOTE: Subjects are being deprecated, please use the new customer APIs. - `type` 'static', required - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `usagePeriod` RecurringPeriod — Recurring period with an interval and an anchor. - `anchor` string, date-time, required — A date-time anchor to base the recurring period on. - `interval` union, required — Period duration for the recurrence - string - 'DAY' | 'WEEK' | 'MONTH' | 'YEAR' — The unit of time for the interval. One of: `day`, `week`, `month`, or `year`. - `intervalISO` string, duration, required — The unit of time for the interval in ISO8601 format. - object — Entitlement template of a boolean entitlement. - `activeFrom` string, date-time, required — The cadence start of the resource. - `activeTo` string, date-time — The cadence end of the resource. - `annotations` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `currentUsagePeriod` Period — A period with a start and end time. - `from` string, date-time, required — Period start time. - `to` string, date-time, required — Period end time. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `featureId` string, required — The feature the subject is entitled to use. - `featureKey` string, required — The feature the subject is entitled to use. - `id` string, required — Readonly unique ULID identifier. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `subjectKey` string, required — The identifier key unique to the subject. NOTE: Subjects are being deprecated, please use the new customer APIs. - `type` 'boolean', required - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `usagePeriod` RecurringPeriod — Recurring period with an interval and an anchor. - `anchor` string, date-time, required — A date-time anchor to base the recurring period on. - `interval` union, required — Period duration for the recurrence - string - 'DAY' | 'WEEK' | 'MONTH' | 'YEAR' — The unit of time for the interval. One of: `day`, `week`, `month`, or `year`. - `intervalISO` string, duration, required — The unit of time for the interval in ISO8601 format. - `feature` Feature, required — Represents a feature that can be enabled or disabled for a plan. Used both for product catalog and entitlements. - `advancedMeterGroupByFilters` object — Optional advanced meter group by filters. You can use this to filter for values of the meter groupBy fields. - `archivedAt` string, date-time — Timestamp of when the resource was archived. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `id` string, required — Readonly unique ULID identifier. - `key` string, required — A key is a unique string that is used to identify a resource. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `meterGroupByFilters` object — Optional meter group by filters. Useful if the meter scope is broader than what feature tracks. Example scenario would be a meter tracking all token use with groupBy fields for the model, then the feature could filter for model=gpt-4. ⚠️ __Deprecated__: Use advancedMeterGroupByFilters instead - `meterSlug` string — A key is a unique string that is used to identify a resource. - `name` string, required - `unitCost` union — Per-unit cost configuration for a feature. Either a fixed manual amount or a dynamic LLM cost lookup. - object — A fixed per-unit cost amount. - `amount` string, required — Numeric represents an arbitrary precision number. - `type` 'manual', required - object — LLM cost lookup configuration. Maps meter group-by dimensions to LLM cost database fields. - `model` string — Static model ID value (e.g., "gpt-4", "claude-3-5-sonnet"). Use this when the feature tracks a single model. Mutually exclusive with `modelProperty`. - `modelProperty` string — Meter group-by property that holds the model ID. Use this when the meter has a group-by dimension for model. Mutually exclusive with `model`. - `pricing` FeatureLLMUnitCostPricing — Resolved per-token pricing from the LLM cost database. - `cacheReadPerToken` string — Numeric represents an arbitrary precision number. - `cacheWritePerToken` string — Numeric represents an arbitrary precision number. - `inputPerToken` string, required — Numeric represents an arbitrary precision number. - `outputPerToken` string, required — Numeric represents an arbitrary precision number. - `reasoningPerToken` string — Numeric represents an arbitrary precision number. - `provider` string — Static LLM provider value (e.g., "openai", "anthropic"). Use this when the feature tracks a single provider. Mutually exclusive with `providerProperty`. - `providerProperty` string — Meter group-by property that holds the LLM provider. Use this when the meter has a group-by dimension for provider. Mutually exclusive with `provider`. - `tokenType` string — Static token type value. Use this when the feature tracks a single token type (e.g., only input tokens). Expected values: input, output, cache_read, reasoning, cache_write, request, response. `request` is an alias for `input`, `response` is an alias for `output`. Mutually exclusive with `tokenTypeProperty`. - `tokenTypeProperty` string — Meter group-by property that holds the token type. Use this when the meter has a group-by dimension for token type. Mutually exclusive with `tokenType`. - `type` 'llm', required - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `limit` number - `unit` Unit — The unit of subscription item. - `plural` string, required - `singular` string, required - `value` EntitlementValue — Entitlements are the core of OpenMeter access management. They define access to features for subjects. Entitlements can be metered, boolean, or static. - `balance` number, double — Only available for metered entitlements. Metered entitlements are built around a balance calculation where feature usage is deducted from the issued grants. Balance represents the remaining balance of the entitlement, it's value never turns negative. - `config` string — Only available for static entitlements. The JSON parsable config of the entitlement. - `hasAccess` boolean, required — Whether the subject has access to the feature. Shared accross all entitlement types. - `overage` number, double — Only available for metered entitlements. Overage represents the usage that wasn't covered by grants, e.g. if the subject had a total feature usage of 100 in the period but they were only granted 80, there would be 20 overage. - `totalAvailableGrantAmount` number, double — Only available for metered entitlements. The summed amount of all grant active at query time PLUS the used amount of since inactive grants. - `usage` number, double — Only available for metered entitlements. Returns the total feature usage in the current period. - `plan` CloudSubscriptionPlan, required — The subscription plan information. - `billingCycle` CloudBillingCycle, required — The subscription billing cycle. - `interval` 'month' | 'year', required — The subscription billing cycle interval. - `intervalCount` integer, required - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `key` string, required — A key is a unique string that is used to identify a resource. - `name` string, required - `trialPeriodDays` integer - `status` 'trialing' | 'active', required — The status of the subscription. - trialing: The subscription is in a trial period - active: The customer has an active free or paid subscription - `trialEligible` boolean - `trialEnd` string, date-time — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. ## Other responses - `400` — The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). - `401` — The request has not been applied because it lacks valid authentication credentials for the target resource. - `403` — The server understood the request but refuses to authorize it. - `412` — One or more conditions given in the request header fields evaluated to false when tested on the server. - `500` — The server encountered an unexpected condition that prevented it from fulfilling the request. - `503` — The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay. - `default` — An unexpected error response. --- [API](https://skmtc.dev/openmeter/apis/openmeter-cloud-api.md) · [All operations](https://skmtc.dev/openmeter/apis/openmeter-cloud-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/openmeter/openmeter-cloud-api/revisions/c9c0ec9cffe9/schema)