> For the complete documentation index, see [llms.txt](https://docs.m-xr.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.m-xr.com/marso-studio-api/api/account.md).
# Account
Inspect your key, credit balance, usage, and prices.
Account endpoints return information about the account associated with the API key used to make the request. Use them to inspect the authenticating key and check the current credit balance. Use them also to read the credit usage history, and the credit price of each PBR action.
## Retrieve the current account.
> Returns the identity of the account associated with the API key and metadata about the API key used\
> to authenticate the request.
```json
{"openapi":"3.1.0","info":{"title":"Marso Studio API","version":"0.0.1"},"tags":[{"name":"account","description":"Account endpoints return information about the account associated with the\nAPI key used to make the request. Use them to inspect the authenticating\nkey and check the current credit balance. Use them also to read the credit\nusage history, and the credit price of each PBR action.\n"}],"servers":[{"url":"https://api.marso.ai/api/public/v1","description":"Production server."}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key minted from the Marso Studio dashboard. The value has the form\n`mxr_live_` and is sent as a Bearer token in the `Authorization`\nheader.\n"}},"schemas":{"AccountMeResponse":{"type":"object","required":["user_id","plan_tier","effective_features","api_key"],"description":"Response from `GET /account/me`. Contains the account's identity and the\nAPI key used to authenticate the request.\n","properties":{"user_id":{"type":"string","description":"Unique identifier of the account.\n"},"email":{"type":"string","description":"Email address associated with the account.\n"},"plan_tier":{"type":"string","description":"Legacy compatibility tier. This value stays `free` for all accounts.\n"},"subscription_plan_code":{"$ref":"#/components/schemas/SubscriptionPlanCode","description":"Opaque code for the personal subscription plan."},"subscription_plan_class":{"$ref":"#/components/schemas/SubscriptionPlanClass","description":"Stable class of the personal subscription plan."},"organization_seat_plan_code":{"$ref":"#/components/schemas/SubscriptionPlanCode","description":"Opaque code for the assigned Organization seat plan."},"organization_seat_plan_class":{"$ref":"#/components/schemas/SubscriptionPlanClass","description":"Stable class of the assigned Organization seat plan."},"effective_features":{"type":"array","description":"Sorted union of features from the personal plan and an assigned\nOrganization seat. The array is empty when subscriptions are off.\n","items":{"$ref":"#/components/schemas/SubscriptionFeature"}},"api_key":{"$ref":"#/components/schemas/AccountAPIKeyMeta"}}},"SubscriptionPlanCode":{"type":"string","pattern":"^plan_[A-Za-z0-9]{7,64}$","description":"Opaque and immutable code for a subscription plan. Use the plan\ncatalogue for its current display name. The code must start with\n`plan_`, followed by 7 to 64 ASCII letters or digits.\n"},"SubscriptionPlanClass":{"type":"string","description":"Stable class of a subscription plan.\n\nPossible enum values:\n- `free`: the Free plan class.\n- `creator`: the Creator plan class.\n- `artist_pro`: the Artist Pro plan class.\n- `studio`: the Studio plan class.\n- `enterprise`: the Enterprise plan class.\n","enum":["free","creator","artist_pro","studio","enterprise"]},"SubscriptionFeature":{"type":"string","description":"Product capability available to the account.\n\nPossible enum values:\n- `commercial_license`: commercial-use rights.\n- `api_pbr`: PBR generation through the Public Platform API.\n- `api_asset_download`: asset downloads through the Public Platform API.\n- `custom_polycount`: custom polygon counts for 3D generation.\n- `image_edit`: image editing.\n- `multiview`: multiview generation.\n","enum":["commercial_license","api_pbr","api_asset_download","custom_polycount","image_edit","multiview"]},"AccountAPIKeyMeta":{"type":"object","required":["prefix","label","created_at"],"description":"Metadata about the API key used to authenticate the request.\n","properties":{"prefix":{"type":"string","description":"Recognizable prefix of the API key, formed as `mxr_live_` followed by\nthe first 7 entropy characters. This lets you identify the key without\nexposing the full secret.\n"},"label":{"type":"string","description":"Human-readable label given to the key in the dashboard.\n"},"created_at":{"$ref":"#/components/schemas/EpochMillis"},"last_used_at":{"$ref":"#/components/schemas/NullableEpochMillis"}}},"EpochMillis":{"type":"integer","format":"int64","description":"Time represented as milliseconds since the Unix epoch.\n"},"NullableEpochMillis":{"type":["integer","null"],"format":"int64","description":"Time represented as milliseconds since the Unix epoch, or `null` when the\nfield has not been set.\n"},"Error":{"type":"object","required":["error"],"description":"Canonical error envelope. The error payload is nested under the `error`\nkey.\n","properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}}},"ErrorBody":{"type":"object","description":"The body of an error response. The `code` is a stable value clients can\nbranch on; the `message` is a human-readable explanation.\n","required":["code","message"],"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable description of the error.\n"},"details":{"type":["object","null"],"description":"Additional structured information about the error, or `null` if no\nextra details are available.\n","additionalProperties":true}}},"ErrorCode":{"type":"string","description":"Machine-readable error code. The enum enumerates every code that can be\nreturned by this API, including infrastructure-level 5xx codes, so\ngenerated clients can decode any `error.code` they receive.\n\nPossible enum values:\n- `INVALID_REQUEST`: the request body or a query parameter failed validation.\n- `MALFORMED_UUID`: a path parameter that should be a UUID is not one.\n- `UNAUTHORIZED`: the request could not be authenticated.\n- `API_KEY_MISSING`: no API key was supplied.\n- `API_KEY_INVALID`: the supplied API key does not match any known key.\n- `API_KEY_REVOKED`: the supplied API key has been revoked.\n- `PLAN_FEATURE_REQUIRED`: the account plan does not include a required feature.\n- `INSUFFICIENT_CREDITS`: the account does not have enough credits for this request.\n- `QUOTA_EXCEEDED`: a usage quota for the account has been exceeded.\n- `FILE_TOO_LARGE`: an uploaded or referenced file exceeds the allowed size.\n- `INVALID_CONTENT_TYPE`: a file's content type does not match its declared or expected type.\n- `UNSUPPORTED_ASSET_FORMAT`: a file's extension is not one of the supported asset formats.\n- `FORMAT_NOT_AVAILABLE`: the requested downloadable format does not exist for this asset.\n- `ASSET_NOT_FOUND`: the asset does not exist or does not belong to the account.\n- `ASSET_IN_USE`: the asset is referenced by an active execution and cannot be deleted.\n- `BATCH_TOO_LARGE`: the batch contains more items than the endpoint allows.\n- `CONCURRENT_EXECUTION_LIMIT_EXCEEDED`: the account has reached its limit on simultaneous submissions.\n- `PBR_FAILURE_CAP_EXCEEDED`: the account has too many recent failed PBR runs; new submissions are temporarily blocked.\n- `EXECUTION_NOT_FOUND`: the execution or batch does not exist or does not belong to the account.\n- `EXECUTION_IN_PROGRESS`: the request conflicts with an execution that is still running.\n- `RATE_LIMITED`: the API key's rate limit was exceeded.\n- `SERVICE_UNAVAILABLE`: a dependent service is temporarily unavailable; retry later.\n- `MAINTENANCE_MODE`: the API is temporarily unavailable for maintenance.\n- `INTERNAL_SERVER_ERROR`: an unexpected server error occurred.\n- `WORKFLOW_CREATION_FAILED`: the platform could not start the underlying workflow.\n- `WORKFLOW_API_ERROR`: the platform's workflow system returned an unexpected error.\n","enum":["INVALID_REQUEST","MALFORMED_UUID","UNAUTHORIZED","API_KEY_MISSING","API_KEY_INVALID","API_KEY_REVOKED","PLAN_FEATURE_REQUIRED","INSUFFICIENT_CREDITS","QUOTA_EXCEEDED","FILE_TOO_LARGE","INVALID_CONTENT_TYPE","UNSUPPORTED_ASSET_FORMAT","FORMAT_NOT_AVAILABLE","ASSET_NOT_FOUND","ASSET_IN_USE","BATCH_TOO_LARGE","CONCURRENT_EXECUTION_LIMIT_EXCEEDED","PBR_FAILURE_CAP_EXCEEDED","EXECUTION_NOT_FOUND","EXECUTION_IN_PROGRESS","RATE_LIMITED","SERVICE_UNAVAILABLE","MAINTENANCE_MODE","INTERNAL_SERVER_ERROR","WORKFLOW_CREATION_FAILED","WORKFLOW_API_ERROR"]}},"responses":{"Unauthorized":{"description":"The API key is missing, invalid, or revoked. Possible error codes:\n`API_KEY_MISSING`, `API_KEY_INVALID`, `API_KEY_REVOKED`, or `UNAUTHORIZED`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded (`RATE_LIMITED`). The response includes a `Retry-After`\nheader with the number of seconds to wait before retrying, plus the\n`X-RateLimit-*` headers. Those headers are also present on successful (2xx)\nresponses so a client can pace itself.\n","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request burst capacity for the API key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current burst window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix epoch seconds when the burst capacity is fully restored.\n","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/account/me":{"get":{"operationId":"getAccountMe","tags":["account"],"summary":"Retrieve the current account.","description":"Returns the identity of the account associated with the API key and metadata about the API key used\nto authenticate the request.\n","responses":{"200":{"description":"Account identity and API key metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountMeResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"Subscription state is temporarily unavailable (`SERVICE_UNAVAILABLE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Retrieve the credit balance.
> Returns the current credit balance for the account associated with the API key, including daily-free\
> and paid credits. Organization pool balances are not exposed.
```json
{"openapi":"3.1.0","info":{"title":"Marso Studio API","version":"0.0.1"},"tags":[{"name":"account","description":"Account endpoints return information about the account associated with the\nAPI key used to make the request. Use them to inspect the authenticating\nkey and check the current credit balance. Use them also to read the credit\nusage history, and the credit price of each PBR action.\n"}],"servers":[{"url":"https://api.marso.ai/api/public/v1","description":"Production server."}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key minted from the Marso Studio dashboard. The value has the form\n`mxr_live_` and is sent as a Bearer token in the `Authorization`\nheader.\n"}},"schemas":{"AccountCreditsResponse":{"type":"object","required":["total_credits","daily_free_credits","paid_credits","billing_source","organization_member"],"description":"Response from `GET /account/credits`. Contains the account's personal\ncredit balance. Organization pool balances are not exposed.\n","properties":{"total_credits":{"type":"integer","format":"int64","description":"Sum of personal daily-free and paid credits. Does not include any\norganization pool balance.\n"},"daily_free_credits":{"type":"integer","format":"int64","description":"Remaining personal daily-free credits.\n"},"paid_credits":{"type":"integer","format":"int64","description":"Remaining personal paid credits.\n"},"billing_source":{"type":"string","enum":["personal","organization"],"description":"Preferred billing source for the account.\n\nPossible enum values:\n- `personal`: charges are applied to the account's personal credits.\n- `organization`: charges are applied to the account's organization\n credits, if available.\n"},"organization_member":{"type":"boolean","description":"Whether the account belongs to an organization. No organization\nidentity or pool balance is exposed in this response.\n"}}},"Error":{"type":"object","required":["error"],"description":"Canonical error envelope. The error payload is nested under the `error`\nkey.\n","properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}}},"ErrorBody":{"type":"object","description":"The body of an error response. The `code` is a stable value clients can\nbranch on; the `message` is a human-readable explanation.\n","required":["code","message"],"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable description of the error.\n"},"details":{"type":["object","null"],"description":"Additional structured information about the error, or `null` if no\nextra details are available.\n","additionalProperties":true}}},"ErrorCode":{"type":"string","description":"Machine-readable error code. The enum enumerates every code that can be\nreturned by this API, including infrastructure-level 5xx codes, so\ngenerated clients can decode any `error.code` they receive.\n\nPossible enum values:\n- `INVALID_REQUEST`: the request body or a query parameter failed validation.\n- `MALFORMED_UUID`: a path parameter that should be a UUID is not one.\n- `UNAUTHORIZED`: the request could not be authenticated.\n- `API_KEY_MISSING`: no API key was supplied.\n- `API_KEY_INVALID`: the supplied API key does not match any known key.\n- `API_KEY_REVOKED`: the supplied API key has been revoked.\n- `PLAN_FEATURE_REQUIRED`: the account plan does not include a required feature.\n- `INSUFFICIENT_CREDITS`: the account does not have enough credits for this request.\n- `QUOTA_EXCEEDED`: a usage quota for the account has been exceeded.\n- `FILE_TOO_LARGE`: an uploaded or referenced file exceeds the allowed size.\n- `INVALID_CONTENT_TYPE`: a file's content type does not match its declared or expected type.\n- `UNSUPPORTED_ASSET_FORMAT`: a file's extension is not one of the supported asset formats.\n- `FORMAT_NOT_AVAILABLE`: the requested downloadable format does not exist for this asset.\n- `ASSET_NOT_FOUND`: the asset does not exist or does not belong to the account.\n- `ASSET_IN_USE`: the asset is referenced by an active execution and cannot be deleted.\n- `BATCH_TOO_LARGE`: the batch contains more items than the endpoint allows.\n- `CONCURRENT_EXECUTION_LIMIT_EXCEEDED`: the account has reached its limit on simultaneous submissions.\n- `PBR_FAILURE_CAP_EXCEEDED`: the account has too many recent failed PBR runs; new submissions are temporarily blocked.\n- `EXECUTION_NOT_FOUND`: the execution or batch does not exist or does not belong to the account.\n- `EXECUTION_IN_PROGRESS`: the request conflicts with an execution that is still running.\n- `RATE_LIMITED`: the API key's rate limit was exceeded.\n- `SERVICE_UNAVAILABLE`: a dependent service is temporarily unavailable; retry later.\n- `MAINTENANCE_MODE`: the API is temporarily unavailable for maintenance.\n- `INTERNAL_SERVER_ERROR`: an unexpected server error occurred.\n- `WORKFLOW_CREATION_FAILED`: the platform could not start the underlying workflow.\n- `WORKFLOW_API_ERROR`: the platform's workflow system returned an unexpected error.\n","enum":["INVALID_REQUEST","MALFORMED_UUID","UNAUTHORIZED","API_KEY_MISSING","API_KEY_INVALID","API_KEY_REVOKED","PLAN_FEATURE_REQUIRED","INSUFFICIENT_CREDITS","QUOTA_EXCEEDED","FILE_TOO_LARGE","INVALID_CONTENT_TYPE","UNSUPPORTED_ASSET_FORMAT","FORMAT_NOT_AVAILABLE","ASSET_NOT_FOUND","ASSET_IN_USE","BATCH_TOO_LARGE","CONCURRENT_EXECUTION_LIMIT_EXCEEDED","PBR_FAILURE_CAP_EXCEEDED","EXECUTION_NOT_FOUND","EXECUTION_IN_PROGRESS","RATE_LIMITED","SERVICE_UNAVAILABLE","MAINTENANCE_MODE","INTERNAL_SERVER_ERROR","WORKFLOW_CREATION_FAILED","WORKFLOW_API_ERROR"]}},"responses":{"Unauthorized":{"description":"The API key is missing, invalid, or revoked. Possible error codes:\n`API_KEY_MISSING`, `API_KEY_INVALID`, `API_KEY_REVOKED`, or `UNAUTHORIZED`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded (`RATE_LIMITED`). The response includes a `Retry-After`\nheader with the number of seconds to wait before retrying, plus the\n`X-RateLimit-*` headers. Those headers are also present on successful (2xx)\nresponses so a client can pace itself.\n","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request burst capacity for the API key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current burst window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix epoch seconds when the burst capacity is fully restored.\n","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/account/credits":{"get":{"operationId":"getAccountCredits","tags":["account"],"summary":"Retrieve the credit balance.","description":"Returns the current credit balance for the account associated with the API key, including daily-free\nand paid credits. Organization pool balances are not exposed.\n","responses":{"200":{"description":"Credit balance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountCreditsResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"The credit service is temporarily unavailable (`SERVICE_UNAVAILABLE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Retrieve credit usage.
> Returns credit consumption over a time range, grouped by UTC day. The\
> \`from\` and \`to\` parameters are Unix millisecond timestamps; \`to\` must be\
> greater than \`from\`, and the requested window must be 90 days or less.
```json
{"openapi":"3.1.0","info":{"title":"Marso Studio API","version":"0.0.1"},"tags":[{"name":"account","description":"Account endpoints return information about the account associated with the\nAPI key used to make the request. Use them to inspect the authenticating\nkey and check the current credit balance. Use them also to read the credit\nusage history, and the credit price of each PBR action.\n"}],"servers":[{"url":"https://api.marso.ai/api/public/v1","description":"Production server."}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key minted from the Marso Studio dashboard. The value has the form\n`mxr_live_` and is sent as a Bearer token in the `Authorization`\nheader.\n"}},"schemas":{"EpochMillis":{"type":"integer","format":"int64","description":"Time represented as milliseconds since the Unix epoch.\n"},"AccountUsageResponse":{"type":"object","required":["total_credits","buckets"],"description":"Response from `GET /account/usage`. Contains credit consumption over the\nrequested time range, grouped by UTC day.\n","properties":{"total_credits":{"type":"integer","format":"int64","description":"Total credits consumed across all days in the requested window.\n"},"buckets":{"type":"array","description":"Per-day credit usage, sorted chronologically.\n","items":{"$ref":"#/components/schemas/AccountUsageBucket"}}}},"AccountUsageBucket":{"type":"object","required":["date","credits"],"description":"One UTC day of credit usage.\n","properties":{"date":{"type":"string","description":"UTC day as an RFC 3339 date string.\n"},"credits":{"type":"integer","format":"int64","description":"Total credits consumed on that day.\n"}}},"Error":{"type":"object","required":["error"],"description":"Canonical error envelope. The error payload is nested under the `error`\nkey.\n","properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}}},"ErrorBody":{"type":"object","description":"The body of an error response. The `code` is a stable value clients can\nbranch on; the `message` is a human-readable explanation.\n","required":["code","message"],"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable description of the error.\n"},"details":{"type":["object","null"],"description":"Additional structured information about the error, or `null` if no\nextra details are available.\n","additionalProperties":true}}},"ErrorCode":{"type":"string","description":"Machine-readable error code. The enum enumerates every code that can be\nreturned by this API, including infrastructure-level 5xx codes, so\ngenerated clients can decode any `error.code` they receive.\n\nPossible enum values:\n- `INVALID_REQUEST`: the request body or a query parameter failed validation.\n- `MALFORMED_UUID`: a path parameter that should be a UUID is not one.\n- `UNAUTHORIZED`: the request could not be authenticated.\n- `API_KEY_MISSING`: no API key was supplied.\n- `API_KEY_INVALID`: the supplied API key does not match any known key.\n- `API_KEY_REVOKED`: the supplied API key has been revoked.\n- `PLAN_FEATURE_REQUIRED`: the account plan does not include a required feature.\n- `INSUFFICIENT_CREDITS`: the account does not have enough credits for this request.\n- `QUOTA_EXCEEDED`: a usage quota for the account has been exceeded.\n- `FILE_TOO_LARGE`: an uploaded or referenced file exceeds the allowed size.\n- `INVALID_CONTENT_TYPE`: a file's content type does not match its declared or expected type.\n- `UNSUPPORTED_ASSET_FORMAT`: a file's extension is not one of the supported asset formats.\n- `FORMAT_NOT_AVAILABLE`: the requested downloadable format does not exist for this asset.\n- `ASSET_NOT_FOUND`: the asset does not exist or does not belong to the account.\n- `ASSET_IN_USE`: the asset is referenced by an active execution and cannot be deleted.\n- `BATCH_TOO_LARGE`: the batch contains more items than the endpoint allows.\n- `CONCURRENT_EXECUTION_LIMIT_EXCEEDED`: the account has reached its limit on simultaneous submissions.\n- `PBR_FAILURE_CAP_EXCEEDED`: the account has too many recent failed PBR runs; new submissions are temporarily blocked.\n- `EXECUTION_NOT_FOUND`: the execution or batch does not exist or does not belong to the account.\n- `EXECUTION_IN_PROGRESS`: the request conflicts with an execution that is still running.\n- `RATE_LIMITED`: the API key's rate limit was exceeded.\n- `SERVICE_UNAVAILABLE`: a dependent service is temporarily unavailable; retry later.\n- `MAINTENANCE_MODE`: the API is temporarily unavailable for maintenance.\n- `INTERNAL_SERVER_ERROR`: an unexpected server error occurred.\n- `WORKFLOW_CREATION_FAILED`: the platform could not start the underlying workflow.\n- `WORKFLOW_API_ERROR`: the platform's workflow system returned an unexpected error.\n","enum":["INVALID_REQUEST","MALFORMED_UUID","UNAUTHORIZED","API_KEY_MISSING","API_KEY_INVALID","API_KEY_REVOKED","PLAN_FEATURE_REQUIRED","INSUFFICIENT_CREDITS","QUOTA_EXCEEDED","FILE_TOO_LARGE","INVALID_CONTENT_TYPE","UNSUPPORTED_ASSET_FORMAT","FORMAT_NOT_AVAILABLE","ASSET_NOT_FOUND","ASSET_IN_USE","BATCH_TOO_LARGE","CONCURRENT_EXECUTION_LIMIT_EXCEEDED","PBR_FAILURE_CAP_EXCEEDED","EXECUTION_NOT_FOUND","EXECUTION_IN_PROGRESS","RATE_LIMITED","SERVICE_UNAVAILABLE","MAINTENANCE_MODE","INTERNAL_SERVER_ERROR","WORKFLOW_CREATION_FAILED","WORKFLOW_API_ERROR"]}},"responses":{"Unauthorized":{"description":"The API key is missing, invalid, or revoked. Possible error codes:\n`API_KEY_MISSING`, `API_KEY_INVALID`, `API_KEY_REVOKED`, or `UNAUTHORIZED`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded (`RATE_LIMITED`). The response includes a `Retry-After`\nheader with the number of seconds to wait before retrying, plus the\n`X-RateLimit-*` headers. Those headers are also present on successful (2xx)\nresponses so a client can pace itself.\n","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request burst capacity for the API key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current burst window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix epoch seconds when the burst capacity is fully restored.\n","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/account/usage":{"get":{"operationId":"getAccountUsage","tags":["account"],"summary":"Retrieve credit usage.","description":"Returns credit consumption over a time range, grouped by UTC day. The\n`from` and `to` parameters are Unix millisecond timestamps; `to` must be\ngreater than `from`, and the requested window must be 90 days or less.\n","parameters":[{"name":"from","in":"query","required":true,"description":"Lower bound on execution `created_at`, as Unix milliseconds (inclusive).","schema":{"$ref":"#/components/schemas/EpochMillis"}},{"name":"to","in":"query","required":true,"description":"Upper bound on execution `created_at`, as Unix milliseconds (exclusive). Must be greater than `from`; window must be 90 days or less.","schema":{"$ref":"#/components/schemas/EpochMillis"}}],"responses":{"200":{"description":"Aggregated credit usage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountUsageResponse"}}}},"400":{"description":"Missing or invalid `from`/`to`, `to` not after `from`, or window exceeds 90 days (`INVALID_REQUEST`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"The usage service is temporarily unavailable (`SERVICE_UNAVAILABLE`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Retrieve PBR credit prices.
> Returns the credit price of every PBR generation action this API can\
> charge, for the account associated with the API key. Prices are per\
> action. A single submit costs the same as one item of the matching batch.\
> To price a batch, multiply its per-item price by the number of items.\
> \
> Prices come from the pricing catalogue that the account holds. The submit\
> endpoints charge against that same catalogue. Read this endpoint instead\
> of storing an amount, because another account can hold another catalogue.
```json
{"openapi":"3.1.0","info":{"title":"Marso Studio API","version":"0.0.1"},"tags":[{"name":"account","description":"Account endpoints return information about the account associated with the\nAPI key used to make the request. Use them to inspect the authenticating\nkey and check the current credit balance. Use them also to read the credit\nusage history, and the credit price of each PBR action.\n"}],"servers":[{"url":"https://api.marso.ai/api/public/v1","description":"Production server."}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key minted from the Marso Studio dashboard. The value has the form\n`mxr_live_` and is sent as a Bearer token in the `Authorization`\nheader.\n"}},"schemas":{"PricingResponse":{"type":"object","required":["pricing_catalogue_id","execution_costs"],"description":"Response from `GET /pricing`. Contains the PBR credit prices that apply to\nthe account associated with the API key.\n","properties":{"pricing_catalogue_id":{"type":"string","description":"ID of the pricing catalogue the prices came from, for example\n`standard-v3`. Quote this value when you report a question about a\ncharge.\n"},"execution_costs":{"$ref":"#/components/schemas/PricingExecutionCosts","description":"The credit price of each PBR generation action."}}},"PricingExecutionCosts":{"type":"object","required":["api_mesh_pbr","api_image_pbr","api_mesh_batch_item","api_image_batch_item"],"additionalProperties":false,"description":"The credit price of one unit of each PBR generation action. Every price is\na whole number of credits and is never negative.\n","properties":{"api_mesh_pbr":{"type":"integer","format":"int64","minimum":0,"description":"Credits charged for one 3D mesh to PBR submit through\n`POST /pbr/execute/mesh`.\n"},"api_image_pbr":{"type":"integer","format":"int64","minimum":0,"description":"Credits charged for one image to PBR submit through\n`POST /pbr/execute/image`.\n"},"api_mesh_batch_item":{"type":"integer","format":"int64","minimum":0,"description":"Credits charged for each item of a 3D mesh to PBR batch submitted\nthrough `POST /batch/pbr/mesh`. Multiply by the number of items for\nthe price of the whole batch.\n"},"api_image_batch_item":{"type":"integer","format":"int64","minimum":0,"description":"Credits charged for each item of an image to PBR batch submitted\nthrough `POST /batch/pbr/image`. Multiply by the number of items for\nthe price of the whole batch.\n"}}},"Error":{"type":"object","required":["error"],"description":"Canonical error envelope. The error payload is nested under the `error`\nkey.\n","properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}}},"ErrorBody":{"type":"object","description":"The body of an error response. The `code` is a stable value clients can\nbranch on; the `message` is a human-readable explanation.\n","required":["code","message"],"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"Human-readable description of the error.\n"},"details":{"type":["object","null"],"description":"Additional structured information about the error, or `null` if no\nextra details are available.\n","additionalProperties":true}}},"ErrorCode":{"type":"string","description":"Machine-readable error code. The enum enumerates every code that can be\nreturned by this API, including infrastructure-level 5xx codes, so\ngenerated clients can decode any `error.code` they receive.\n\nPossible enum values:\n- `INVALID_REQUEST`: the request body or a query parameter failed validation.\n- `MALFORMED_UUID`: a path parameter that should be a UUID is not one.\n- `UNAUTHORIZED`: the request could not be authenticated.\n- `API_KEY_MISSING`: no API key was supplied.\n- `API_KEY_INVALID`: the supplied API key does not match any known key.\n- `API_KEY_REVOKED`: the supplied API key has been revoked.\n- `PLAN_FEATURE_REQUIRED`: the account plan does not include a required feature.\n- `INSUFFICIENT_CREDITS`: the account does not have enough credits for this request.\n- `QUOTA_EXCEEDED`: a usage quota for the account has been exceeded.\n- `FILE_TOO_LARGE`: an uploaded or referenced file exceeds the allowed size.\n- `INVALID_CONTENT_TYPE`: a file's content type does not match its declared or expected type.\n- `UNSUPPORTED_ASSET_FORMAT`: a file's extension is not one of the supported asset formats.\n- `FORMAT_NOT_AVAILABLE`: the requested downloadable format does not exist for this asset.\n- `ASSET_NOT_FOUND`: the asset does not exist or does not belong to the account.\n- `ASSET_IN_USE`: the asset is referenced by an active execution and cannot be deleted.\n- `BATCH_TOO_LARGE`: the batch contains more items than the endpoint allows.\n- `CONCURRENT_EXECUTION_LIMIT_EXCEEDED`: the account has reached its limit on simultaneous submissions.\n- `PBR_FAILURE_CAP_EXCEEDED`: the account has too many recent failed PBR runs; new submissions are temporarily blocked.\n- `EXECUTION_NOT_FOUND`: the execution or batch does not exist or does not belong to the account.\n- `EXECUTION_IN_PROGRESS`: the request conflicts with an execution that is still running.\n- `RATE_LIMITED`: the API key's rate limit was exceeded.\n- `SERVICE_UNAVAILABLE`: a dependent service is temporarily unavailable; retry later.\n- `MAINTENANCE_MODE`: the API is temporarily unavailable for maintenance.\n- `INTERNAL_SERVER_ERROR`: an unexpected server error occurred.\n- `WORKFLOW_CREATION_FAILED`: the platform could not start the underlying workflow.\n- `WORKFLOW_API_ERROR`: the platform's workflow system returned an unexpected error.\n","enum":["INVALID_REQUEST","MALFORMED_UUID","UNAUTHORIZED","API_KEY_MISSING","API_KEY_INVALID","API_KEY_REVOKED","PLAN_FEATURE_REQUIRED","INSUFFICIENT_CREDITS","QUOTA_EXCEEDED","FILE_TOO_LARGE","INVALID_CONTENT_TYPE","UNSUPPORTED_ASSET_FORMAT","FORMAT_NOT_AVAILABLE","ASSET_NOT_FOUND","ASSET_IN_USE","BATCH_TOO_LARGE","CONCURRENT_EXECUTION_LIMIT_EXCEEDED","PBR_FAILURE_CAP_EXCEEDED","EXECUTION_NOT_FOUND","EXECUTION_IN_PROGRESS","RATE_LIMITED","SERVICE_UNAVAILABLE","MAINTENANCE_MODE","INTERNAL_SERVER_ERROR","WORKFLOW_CREATION_FAILED","WORKFLOW_API_ERROR"]}},"responses":{"Unauthorized":{"description":"The API key is missing, invalid, or revoked. Possible error codes:\n`API_KEY_MISSING`, `API_KEY_INVALID`, `API_KEY_REVOKED`, or `UNAUTHORIZED`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded (`RATE_LIMITED`). The response includes a `Retry-After`\nheader with the number of seconds to wait before retrying, plus the\n`X-RateLimit-*` headers. Those headers are also present on successful (2xx)\nresponses so a client can pace itself.\n","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request burst capacity for the API key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current burst window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix epoch seconds when the burst capacity is fully restored.\n","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/pricing":{"get":{"operationId":"getPricing","tags":["account"],"summary":"Retrieve PBR credit prices.","description":"Returns the credit price of every PBR generation action this API can\ncharge, for the account associated with the API key. Prices are per\naction. A single submit costs the same as one item of the matching batch.\nTo price a batch, multiply its per-item price by the number of items.\n\nPrices come from the pricing catalogue that the account holds. The submit\nendpoints charge against that same catalogue. Read this endpoint instead\nof storing an amount, because another account can hold another catalogue.\n","responses":{"200":{"description":"PBR credit prices for the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricingResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"This API cannot resolve the pricing catalogue that the account holds,\nor that catalogue does not price every PBR action\n(`SERVICE_UNAVAILABLE`). The submit endpoints fail the same way, so\nthis endpoint never reports a price that it cannot charge.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.m-xr.com/marso-studio-api/api/account.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.