> ## 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 https://app.stainless.com/api/spec/documented/stigg/openapi.documented.yml get /api/v1/credits/usage openapi: 3.0.0 info: title: Stigg API description: Stigg API documentation version: 7.80.3 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 points: - timestamp: '2024-01-01T00:00:00.000Z' value: 500 - timestamp: '2024-01-02T00:00:00.000Z' value: 750 - timestamp: '2024-01-03T00:00:00.000Z' value: 250 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 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 required: - timestamp - value 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 - 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 - 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 - 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 nullable: true 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 nullable: true required: - message - code NotFoundErrorResponseDto: type: object properties: message: type: string code: type: string enum: - CustomerNotFound - CustomCurrencyNotFound - CreditGrantNotFound - 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 ````