> ## Documentation Index > Fetch the complete documentation index at: https://docs.stigg.io/llms.txt > Use this file to discover all available pages before exploring further. # Get credit usage > Retrieves credit usage time-series data for a customer, grouped by feature, over a specified time range. ## OpenAPI ````yaml /openapi/stigg-api.documented.yml get /api/v1/credits/usage openapi: 3.0.0 info: title: Stigg API description: Stigg API documentation version: 8.64.1 contact: {} servers: - url: https://api.stigg.io description: Production security: - ApiKeyAuth: [] tags: - name: Customers description: Operations related to customers - name: Subscriptions description: Operations related to subscriptions - name: Coupons description: Operations related to coupons - name: Bulk Import description: Operations related to import of customers and subscriptions - name: Usage description: Operations related to usage & metering - name: Promotional Entitlements description: Operations related to promotional entitlements - name: Products description: Operations related to products - name: Features description: Operations related to features - name: Addons description: Operations related to addons - name: Plans description: Operations related to plans - name: Credit grants description: Operations related to credit grants - name: Credit ledger description: Operations related to credit ledger - name: Custom currencies description: Operations related to custom currencies paths: /api/v1/credits/usage: get: tags: - Credit usage summary: Get credit usage description: >- Retrieves credit usage time-series data for a customer, grouped by feature, over a specified time range. operationId: CreditUsageController_getCreditUsage parameters: - name: limit required: false in: query description: Maximum number of items to return schema: minimum: 1 maximum: 100 default: 20 type: integer - name: after required: false in: query description: Return items that come after this cursor schema: maxLength: 255 type: string - name: before required: false in: query description: Return items that come before this cursor schema: maxLength: 255 type: string - name: customerId required: true in: query description: Filter by customer ID (required) schema: minLength: 1 maxLength: 255 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.@-]*$ type: string - name: resourceId required: false in: query description: Filter by resource ID schema: minLength: 1 maxLength: 255 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ type: string - name: currencyId required: false in: query description: Filter by currency ID schema: minLength: 1 maxLength: 255 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ type: string - name: timeRange required: false in: query description: >- Time range for usage data (LAST_DAY, LAST_WEEK, LAST_MONTH, LAST_YEAR). Defaults to LAST_MONTH schema: enum: - LAST_DAY - LAST_WEEK - LAST_MONTH - LAST_YEAR type: string - name: startDate required: false in: query description: >- Start date for the credit usage time range (ISO 8601). Takes precedence over timeRange when provided schema: format: date-time type: string - name: endDate required: false in: query description: >- End date for the credit usage time range (ISO 8601). Defaults to now when startDate is provided schema: format: date-time type: string - name: groupBy required: false in: query description: >- Comma-separated list of feature dimension keys to group usage series by (up to 3). Each key matches /^[a-zA-Z0-9_$-]+$/ schema: maxLength: 255 type: string - name: X-ACCOUNT-ID in: header description: >- Account ID — optional when authenticating with a user JWT (Bearer token); falls back to the user's first membership. Ignored for API-key auth. required: false schema: type: string - name: X-ENVIRONMENT-ID in: header description: >- Environment ID — required when authenticating with a user JWT (Bearer token) on environment-scoped endpoints. Ignored for API-key auth (env is intrinsic to the key). required: false schema: type: string responses: '200': description: Credit usage data with time-series points per feature. content: application/json: schema: $ref: '#/components/schemas/CreditUsageResponseDto' examples: default: value: data: series: - featureId: feature-tokens featureName: API Tokens totalCredits: 1500 eventCount: 60 points: - timestamp: '2024-01-01T00:00:00.000Z' value: 500 eventCount: 20 - timestamp: '2024-01-02T00:00:00.000Z' value: 750 eventCount: 30 - timestamp: '2024-01-03T00:00:00.000Z' value: 250 eventCount: 10 currency: currencyId: credits displayName: Credits symbol: null singular: credit plural: credits pagination: next: null prev: null '400': description: bad request. content: application/json: schema: $ref: '#/components/schemas/BadInputErrorResponseDto' '401': description: User is not authenticated. content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedErrorResponseDto' '403': description: User is not allowed to access this resource. content: application/json: schema: $ref: '#/components/schemas/ForbiddenErrorResponseDto' '404': description: CreditUsage not found. content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponseDto' '429': description: Too many requests. content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponseDto' x-codeSamples: - lang: JavaScript source: >- import Stigg from '@stigg/typescript'; const client = new Stigg({ apiKey: process.env['STIGG_API_KEY'], // This is the default and can be omitted }); const response = await client.v1.credits.getUsage({ customerId: 'customerId' }); console.log(response.data); - lang: Python source: |- import os from stigg import Stigg client = Stigg( api_key=os.environ.get("STIGG_API_KEY"), # This is the default and can be omitted ) response = client.v1.credits.get_usage( customer_id="customerId", ) print(response.data) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/stiggio/stigg-go\"\n\t\"github.com/stiggio/stigg-go/option\"\n)\n\nfunc main() {\n\tclient := stigg.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.V1.Credits.GetUsage(context.TODO(), stigg.V1CreditGetUsageParams{\n\t\tCustomerID: \"customerId\",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\n}\n" - lang: Java source: |- package io.stigg.example; import io.stigg.client.StiggClient; import io.stigg.client.okhttp.StiggOkHttpClient; import io.stigg.models.v1.credits.CreditGetUsageParams; import io.stigg.models.v1.credits.CreditGetUsageResponse; public final class Main { private Main() {} public static void main(String[] args) { StiggClient client = StiggOkHttpClient.fromEnv(); CreditGetUsageParams params = CreditGetUsageParams.builder() .customerId("customerId") .build(); CreditGetUsageResponse response = client.v1().credits().getUsage(params); } } - lang: Ruby source: |- require "stigg" stigg = Stigg::Client.new(api_key: "My API Key") response = stigg.v1.credits.get_usage(customer_id: "customerId") puts(response) - lang: C# source: >- using System; using Stigg.Client; using Stigg.Client.Models.V1.Credits; StiggClient client = new(); CreditGetUsageParams parameters = new() { CustomerID = "customerId" }; var response = await client.V1.Credits.GetUsage(parameters); Console.WriteLine(response); - lang: CLI source: |- stigg v1:credits get-usage \ --api-key 'My API Key' \ --customer-id customerId components: schemas: CreditUsageResponseDto: type: object properties: data: type: object properties: series: type: array items: type: object properties: featureId: type: string maxLength: 255 description: The feature ID; null when grouping by dimensions only nullable: true featureName: type: string maxLength: 255 description: >- The display name of the feature; null when grouping by dimensions only nullable: true totalCredits: type: number description: Total credits consumed by this feature in the time range eventCount: type: number description: >- Number of distinct usage events that consumed credits in this series. This count is not additive across series, because an event matched by several meters appears in more than one series. points: type: array items: type: object properties: timestamp: type: string format: date-time description: The timestamp of the data point value: type: number description: The credit usage value at this point eventCount: type: number description: >- Number of distinct usage events that consumed credits in this time bucket required: - timestamp - value - eventCount title: CreditUsagePoint description: A single data point in the credit usage time series description: Time-series data points for this feature tags: type: array items: type: object properties: key: type: string maxLength: 255 description: The dimension key value: type: string maxLength: 255 description: The dimension value for this series required: - key - value title: CreditUsageSeriesTag description: >- Dimension key/value pair identifying a credit usage series description: >- Dimension key/value pairs identifying this series when groupBy is applied required: - featureId - featureName - totalCredits - eventCount - points title: CreditUsageSeries description: Credit usage data for a single feature description: Credit usage series grouped by feature currency: type: object properties: currencyId: type: string maxLength: 255 description: The currency identifier displayName: type: string maxLength: 255 description: The display name of the currency symbol: type: string maxLength: 255 description: The currency symbol nullable: true singular: type: string maxLength: 255 description: Singular unit label nullable: true plural: type: string maxLength: 255 description: Plural unit label nullable: true required: - currencyId - displayName - symbol - singular - plural title: CreditUsageCurrency description: The custom currency used for credit measurement nullable: true pagination: type: object properties: next: type: string maxLength: 255 description: >- Cursor for fetching the next page of results, or null if no additional pages exist nullable: true prev: type: string maxLength: 255 description: >- Cursor for fetching the previous page of results, or null if at the beginning nullable: true required: - next - prev description: >- Cursor-based pagination for the returned series. `next`/`prev` are opaque cursors; pass them back as `after`/`before` to traverse pages. The series axis is `groupBy` when provided, otherwise `featureId` required: - series - currency - pagination title: CreditUsage description: Credit usage data grouped by feature with time-series points required: - data title: Response description: Response object BadInputErrorResponseDto: type: object properties: message: type: string code: type: string enum: - BadUserInput - EnvironmentMismatch - BillingContractOperationRejected - DuplicateIntegrationNotAllowed - EntityIsArchivedError - IntegrityViolation - FreePlanCantHaveCompatiblePackageGroupError - SubscriptionMustHaveSinglePlanError - AddonIsCompatibleWithPlan - AddonIsCompatibleWithGroup - DuplicateAddonProvisionedError - ScheduledMigrationAlreadyExistsError - SubscriptionAlreadyOnLatestPlan - EntityIdDifferentFromRefIdError - UnsupportedFeatureType - UnsupportedVendorIdentifier - UnsupportedSubscriptionScheduleType - InvalidEntitlementResetPeriod - IncompatibleSubscriptionAddon - UnPublishedPackage - MeteringNotAvailableForFeatureType - AuthCustomerMismatch - AuthCustomerReadonly - FetchAllCountriesPricesNotAllowed - MemberInvitationError - PlansCircularDependencyError - NoFeatureEntitlementInSubscription - CheckoutIsNotSupported - UnsupportedParameter - PricingModelNotSupportedByBillingIntegration - BillingIntegrationMissing - BillingIntegrationAlreadyExistsError - InvalidMemberDelete - PackageAlreadyPublished - DraftPlanCantBeArchived - DraftAddonCantBeArchived - PlanWithChildCantBeDeleted - PlanCannotBePublishWhenBasePlanIsDraft - PlanCannotBePublishWhenCompatibleAddonIsDraft - PlanIsUsedAsDefaultStartPlan - PlanIsUsedAsDowngradePlan - InvalidAddressError - InvalidQuantity - BillingPeriodMissingError - DowngradeBillingPeriodNotSupportedError - CustomerAlreadyUsesCouponError - CustomerAlreadyHaveCustomerCoupon - SubscriptionAlreadyCanceledOrExpired - TrialMustBeCancelledImmediately - SubscriptionDoesNotHaveBillingPeriod - InvalidCancellationDate - FailedToImportCustomer - FailedToImportSubscriptions - PackagePricingTypeNotSet - InvalidSubscriptionStatus - InvalidArgumentError - EditAllowedOnDraftPackageOnlyError - ResyncAlreadyInProgress - ArchivedCouponCantBeApplied - ImportAlreadyInProgress - AddonHasToHavePriceError - SelectedBillingModelDoesntMatchImportedItemError - CannotArchiveProductError - CannotUnarchiveProductError - CannotDeleteCustomerError - CannotRemovePaymentMethodFromCustomerError - CannotDeleteFeatureError - CannotArchiveFeatureError - InvalidUpdatePriceUnitAmountError - ExperimentAlreadyRunning - ExperimentStatusError - OperationNotAllowedDuringInProgressExperiment - EntitlementsMustBelongToSamePackage - CanNotUpdateEntitlementsFeatureGroup - MeterMustBeAssociatedToMeteredFeature - CannotUpdateMeterOfFeatureInUse - CannotEditPackageInNonDraftMode - CannotAddOverrideEntitlementToPlan - MissingEntityIdError - NoProductsAvailable - PromotionCodeNotForCustomer - PromotionCodeNotActive - PromotionCodeMaxRedemptionsReached - PromotionCodeMinimumAmountNotReached - PromotionCodeCustomerNotFirstPurchase - AddonWithDraftCannotBeDeletedError - CannotReportUsageForEntitlementWithMeterError - RecalculateEntitlementsError - ImportSubscriptionsBulkError - InvalidMetadataError - CannotUpsertToPackageThatHasDraft - IntegrationValidationError - AwsMarketplaceIntegrationValidationError - AwsMarketplaceIntegrationError - DataExportIntegrationError - HubspotIntegrationError - DuplicateProductValidationError - AmountTooLarge - CustomerHasNoEmailAddress - MergeEnvironmentValidationError - EntitlementLimitExceededError - EntitlementUsageOutOfRangeError - UsageMeasurementDiffOutOfRangeError - AddonQuantityExceedsLimitError - AddonDependencyMissingError - PackageGroupMinItemsError - CannotUpdateUnitTransformationError - SingleSubscriptionCantBeAutoCancellationTargetError - MultiSubscriptionCantBeAutoCancellationSourceError - ChangingPayingCustomerIsNotSupportedError - RequiredSsoAuthenticationError - InvalidDoggoSignatureError - InvalidReceivedSignatureError - CannotDeleteDefaultIntegration - CannotChangeBillingIntegration - FailedToResolveBillingIntegration - WorkflowTriggerNotFound - DeprecatedEstimateSubscriptionError - FeatureConfigurationExceededLimitError - FeatureNotBelongToFeatureGroupError - FeatureGroupMissingFeaturesError - VersionExceedsMaxValueError - CannotUpdateExpireAtForExpiredCreditGrantError - ExpireAtMustBeLaterThanEffectiveAtError - OfferAlreadyExists - DraftAlreadyExists - CreditGrantAlreadyVoided - CreditGrantCannotBeVoided - InvalidTaxId - ObjectAlreadyBeingUsedByAnotherRequestError - TooManySubscriptionsPerCustomer - TooManyCustomCurrencies - StripeError - SchedulingAtEndOfBillingPeriod - ApiKeyExpired - ApiKeyHasExpiry - OveragePriceNotSupportedOnAddon - OveragePriceRequiresUsageLimit - InvalidCreditOverageBillingModel - CreditOveragePriceCurrencyNotFound - InvoicePreviewNotAvailableForDraftContract nullable: true reason: type: string maxLength: 255 description: >- The billing side's machine-readable code for a billing-contract refusal. Present only when the code is BillingContractOperationRejected and the refusal carried one. required: - message - code UnauthenticatedErrorResponseDto: type: object properties: message: type: string code: type: string enum: - Unauthenticated nullable: true required: - message - code ForbiddenErrorResponseDto: type: object properties: message: type: string code: type: string enum: - IdentityForbidden - AccessDeniedError - NoFeatureEntitlementError - GovernanceNotEnabled nullable: true required: - message - code NotFoundErrorResponseDto: type: object properties: message: type: string code: type: string enum: - CustomerNotFound - CustomCurrencyNotFound - CreditGrantNotFound - ContractNotFound - InvoiceNotFound - MemberNotFound - PackageGroupNotFound - AddonNotFound - AddonsNotFound - EnvironmentMissing - IntegrationNotFound - VendorIsNotSupported - CouponNotFound - FutureUpdateNotFound - CustomerNoBillingId - SubscriptionNoBillingId - StripeCustomerIsDeleted - InitStripePaymentMethodError - PreparePaymentMethodFormError - AccountNotFoundError - ExperimentNotFoundError - NoDraftOfferFound - PromotionCodeNotFound - FailedToCreateCheckoutSessionError - PaymentMethodNotFoundError - ProductNotFoundError - ProductNotPublishedError - MissingBillingInvoiceError - BillingInvoiceStatusError - FeatureGroupNotFoundError - CannotArchiveFeatureGroupError - OfferNotFound - CustomerResourceNotFound - FeatureNotFound - PriceNotFound - NoActiveSubscriptionForCustomer - PlanNotFound - PromotionalEntitlementNotFoundError - SubscriptionNotFound - ApiKeyNotFound nullable: true required: - message - code TooManyRequestsErrorResponseDto: type: object properties: message: type: string code: type: string enum: - RateLimitExceeded nullable: true required: - message - code securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY description: Server API Key ```` ## Related topics - [Node.js SDK](/api-and-sdks/changelog/backend-graphql/node.md) - [Python SDK](/api-and-sdks/changelog/backend-graphql/python.md) - [Ruby SDK](/api-and-sdks/changelog/backend-graphql/ruby.md) - [Sidecar SDK](/api-and-sdks/changelog/backend-graphql/sidecar.md) - [Sidecar Service](/api-and-sdks/changelog/backend-graphql/sidecar-service.md)