> ## Documentation Index
> Fetch the complete documentation index at: https://sorank.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get current business quotas and the AI credit wallet without consuming them

> `quotas` lists the article generation and GEO analysis quotas.
`ai_credits` is the site's AI credit wallet: what can be spent now and
the price of each paid action (keyword research, keyword generation
runs, audit fixes and rewrites). Read it before a paid command.




## OpenAPI

````yaml /api-reference/openapi.yaml get /profiles/{profile_id}/quotas
openapi: 3.1.0
info:
  title: SORANK Public API
  version: 1.2.0
  description: >
    Versioned REST contract for user-delegated SORANK access, served under

    `/api/public/v1`. Contract 1.1 adds products, Search Console and AI traffic

    analytics, extended GEO reads and site settings to the same version path.

    Contract 1.2 adds keyword research and keyword generation runs, the site

    audit with its fixes, product catalog refresh, article indexing status, GEO

    prompt management, backlink exchange settings and quests, invoices, and the

    AI credit wallet in `getQuotas`. Keyword research and audit fixes spend AI

    credits at the application's prices; an insufficient balance returns 402

    `insufficient_credits` with `details.required` and `details.balance`. The
    1.2

    operations need scopes that credentials issued earlier do not hold.

    Keyword research, keyword runs and audit starts run at most once per

    idempotency key: while a request with the key is still running, another one

    answers 409 `operation_in_progress` (retry shortly), and a keyword run or

    audit start whose earlier attempt stopped before reporting its result

    answers 409 `operation_interrupted` (check the current state, then use a

    new key).

    Availability of each operation depends on the deployed backend version and

    the public API feature flag.

    OAuth tokens are resource-bound to the REST API. Personal API keys may use

    REST only when their transport grant permits it. Browser session cookies and

    Supabase tokens are not credentials for this surface.


    Every request is checked against the credential's exact scopes, explicit

    profile allowlist and the actor's current profile access. The resource owner

    and billable account are resolved server-side. A revoked or expired
    credential

    is rejected even on idempotent replay and operation polling.


    Eligibility: the user must have completed Sorank onboarding and the accessed

    site must have a valid subscription (the owner's subscription for an agency

    collaborator; a site without a subscription is not eligible). Eligibility is

    checked at OAuth consent, at personal key creation and replacement, and
    again

    on every REST request and MCP tool call, including idempotent replays and

    operation polling. An incomplete onboarding returns 403

    `onboarding_required`; an ineligible site returns 402
    `subscription_required`

    with `details.reason`. `listProfiles` returns only the eligible sites of the

    grant; operations without a profile require at least one eligible site.


    All mutations require `Idempotency-Key`. Repeating an identical command with

    the same key returns its original receipt after fresh authorization; a
    changed

    command with the same key returns 409. An accepted asynchronous command may

    still fail later. Do not treat an accepted batch as wholly complete: an

    article generation batch returns HTTP 202 with a receipt already `succeeded`

    (the acceptance is the command's outcome), and each generated article is
    then

    followed through `getArticle` or `listArticles` from the receipt's accepted
    IDs.

    Settings commands return the resulting settings and the asynchronous

    `effects` they queued.


    Errors use one envelope everywhere, including authentication and rate-limit

    middlewares: `{"error": {"code", "message", "request_id", "retryable",

    "details"?}}`. MCP tool errors carry the same `code`, `message`,

    `request_id`, `retryable` and `details` in the tool error result. Codes are

    stable snake_case identifiers; each operation lists the codes it can return

    in `x-error-codes`, and REST and MCP return the same code for the same
    cause.


    Error statuses: 400 invalid request (`invalid_request`, `invalid_id`,

    `invalid_idempotency_key` and field-specific validation codes such as

    `invalid_limit`, `invalid_range`, `field_not_writable` for a read-only field

    like `website_url`, `invalid_market`, `invalid_competitor_selection`,

    `too_many_competitors` or `invalid_url`); 401

    missing/invalid/expired/revoked credential (`invalid_credential`, with a

    `WWW-Authenticate` challenge carrying `resource_metadata`); 402

    `subscription_required` (with `details.reason` among `paused`, `past_due`,

    `incomplete`, `inactive` when known) or `insufficient_quota` for business

    quotas; 403 `missing_scope` or `onboarding_required`; 404 `not_found` for an

    inaccessible or unknown resource; 409 conflicts: `idempotency_conflict` (the

    key belongs to a different command), `calendar_busy` (retryable),

    `calendar_changed` (read the current calendar before retrying),

    `publication_busy` (retryable), `resource_busy` (retryable),

    `keyword_already_published`, `article_identity_conflict`,

    `slug_already_exists`, `audit_rewrite_restored` (the audit rewrite was

    restored to the original article; it cannot be pushed live again),

    `product_catalog_cursor_stale` (restart the

    product list from the first page), `business_brief_revision_conflict`

    (read the settings again),

    `youtube_source_replacement_required` (send `replace: true`),

    `youtube_source_purge_in_progress` (retryable, with `Retry-After`);

    `gsc_not_connected`, `ga_not_connected` (connect Google in Sorank); 422
    unsupported provider capability or state

    (`unsupported_capability`, `unsupported_category`, `cms_not_connected`,

    `publication_state_invalid`, `youtube_channel_unsupported`,

    `youtube_channel_not_found`, ...); 403 `google_access_lost` (with

    `details.reason` among `scope_missing`, `property_access_denied`,

    `token_expired`, `ga_permissions_lost`, `ga_property_unavailable`;

    reconnect Google in Sorank); 429 `rate_limited` or `youtube_rate_limited`

    (retryable, with `Retry-After` and `details.retry_after_seconds` when a

    delay is known); 500 `internal_error` for unexpected failures only; 503

    `auth_state_unavailable` or `rate_limit_unavailable` (retryable), with

    access denied until the state recovers, `service_unavailable` (retryable,

    with `Retry-After`: Sorank itself is temporarily unavailable, for example

    its database, or the request exhausted its server time budget),

    `google_unavailable` or

    `youtube_unavailable` (retryable), or `youtube_feature_disabled` (not

    retryable: the integration is disabled on this deployment); 504 `ga_timeout`
    (retryable with a shorter range).


    Each operation has an MCP tool named by `x-mcp-tool`. Tool arguments are

    flat: `profile_id` and `id` for the path parameters, `idempotency_key` for

    the header, plus the query or body fields of the operation; list and batch

    bounds follow the deployment configuration. A tool result carries exactly

    the REST response body (`data` and `meta`).
servers:
  - url: /api/public/v1
security:
  - OAuth2: []
  - PersonalAPIKey: []
tags:
  - name: Profiles
    description: Accessible SEO profiles, capabilities and business quotas.
  - name: Keywords and GEO
    description: >-
      Existing keyword suggestions, GEO analysis results and GEO aggregates as
      shown by the Sorank dashboard.
  - name: Audit
    description: >-
      Site audit (Improvements) of the blog pages, their issues and the fixes
      paid with AI credits.
  - name: Products
    description: Product catalog discovered on the profile's site.
  - name: Backlinks
    description: Backlink exchange participation, backlink credits and quests.
  - name: Billing
    description: Invoices of the site subscription.
  - name: Analytics
    description: |
      Live Google Search Console and Google Analytics 4 reads, as shown by the
      Sorank dashboard. Each call queries Google; it may refresh and store the
      site's Google access token, never forces a cache refresh, and is charged
      to a dedicated analytics rate budget lower than other reads. Google
      Analytics exposure is limited to traffic coming from AI assistants.
  - name: Settings
    description: |
      Site settings as the Sorank settings pages show them to the same user,
      published as an allowlist: no owner identifier, homepage screenshot,
      connection field, storage path, signed URL or technical error.
  - name: Articles
    description: Local article reading, editing and generation.
  - name: Calendar
    description: Automatic editorial calendar and slot management.
  - name: Publication
    description: CMS publication, updates and scheduling.
  - name: Operations
    description: Durable command receipts and outcome polling.
paths:
  /profiles/{profile_id}/quotas:
    get:
      tags:
        - Profiles
      summary: >-
        Get current business quotas and the AI credit wallet without consuming
        them
      description: |
        `quotas` lists the article generation and GEO analysis quotas.
        `ai_credits` is the site's AI credit wallet: what can be spent now and
        the price of each paid action (keyword research, keyword generation
        runs, audit fixes and rewrites). Read it before a paid command.
      operationId: getQuotas
      parameters:
        - $ref: '#/components/parameters/ProfileID'
      responses:
        '200':
          $ref: '#/components/responses/Quotas'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Error'
      security:
        - OAuth2:
            - quotas:read
        - PersonalAPIKey: []
components:
  parameters:
    ProfileID:
      name: profile_id
      in: path
      required: true
      description: >-
        Profile UUID; must be in the grant allowlist and currently accessible to
        the actor.
      schema:
        $ref: '#/components/schemas/UUID'
  responses:
    Quotas:
      description: Current plan and business quotas.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QuotasEnvelope'
    Unauthorized:
      description: Credential missing, invalid, expired or revoked.
      headers:
        WWW-Authenticate:
          description: Bearer challenge with configured resource metadata where applicable.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Error:
      description: Error response; see status-to-code mapping in API description.
      headers:
        Retry-After:
          description: >-
            Seconds until retry when HTTP 429 is returned, with 409
            youtube_source_purge_in_progress, or with 503 service_unavailable.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  schemas:
    UUID:
      type: string
      format: uuid
    QuotasEnvelope:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: '#/components/schemas/QuotasData'
        meta:
          $ref: '#/components/schemas/Meta'
    ErrorEnvelope:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      examples:
        - error:
            code: insufficient_quota
            message: The current article generation quota is exhausted.
            request_id: 33333333-3333-4333-8333-333333333333
            retryable: false
    QuotasData:
      type: object
      additionalProperties: false
      required:
        - profile_id
        - quotas
        - ai_credits
      properties:
        profile_id:
          $ref: '#/components/schemas/UUID'
        quotas:
          type: array
          items:
            $ref: '#/components/schemas/QuotaData'
        ai_credits:
          $ref: '#/components/schemas/AICreditsData'
    Meta:
      type: object
      additionalProperties: false
      required:
        - request_id
      properties:
        request_id:
          $ref: '#/components/schemas/UUID'
        pagination:
          $ref: '#/components/schemas/Pagination'
        catalog:
          $ref: '#/components/schemas/ProductCatalogMeta'
    ErrorBody:
      type: object
      additionalProperties: false
      required:
        - code
        - message
        - request_id
        - retryable
      properties:
        code:
          type: string
          description: Stable public error code; never a raw SQL, CMS or provider error.
          examples:
            - insufficient_quota
            - unsupported_capability
        message:
          type: string
        request_id:
          $ref: '#/components/schemas/UUID'
        retryable:
          type: boolean
          description: |
            True when repeating the same request later, unchanged and with the
            same Idempotency-Key, may succeed (transient busy state, rate limit,
            unavailable authorization or rate-limit state). False when the
            request or the resource state must change first.
        details:
          type: object
          additionalProperties: true
          description: >-
            Safe structured details only (for example `reason` for
            `subscription_required`); no tokens, prompts or internal commands.
    QuotaData:
      type: object
      additionalProperties: false
      description: |
        One business quota of the profile owner.
        `article_generations` counts generations in the current billing period
        and renews at its end. `geo_analyses` follows the GEO analysis rules:
        `remaining` is 0 whenever a new analysis is not allowed right now
        (720-hour cooldown after the last analysis, i.e. one analysis per
        month, paused subscription or consumed free analysis) and `limit`
        otherwise; `used` is `limit - remaining`; `renews_at` is the end of the
        running cooldown or pause, and null when an analysis is available now or
        when access never renews by waiting (the free analysis is granted once;
        a subscription restores access). `analysis_cadence_days` is the number
        of days between automatic analyses and is present only on
        `geo_analyses`.
      required:
        - name
        - limit
        - used
        - remaining
        - renews_at
      properties:
        name:
          type: string
          enum:
            - article_generations
            - geo_analyses
        limit:
          type: integer
          minimum: 0
        used:
          type: integer
          minimum: 0
        remaining:
          type: integer
          minimum: 0
        renews_at:
          type:
            - string
            - 'null'
          format: date-time
        analysis_cadence_days:
          type: integer
          minimum: 1
          description: Days between automatic GEO analyses. Present only on `geo_analyses`.
    AICreditsData:
      type: object
      additionalProperties: false
      description: |
        AI credit wallet of the site. The credits pay keyword research,
        keyword generation runs, audit fixes and audit rewrites. The monthly
        grant does not roll over; purchased credits never expire.
      required:
        - enabled
        - balance
        - monthly_grant
        - monthly_grant_remaining
        - purchased_balance
        - renews_at
        - costs
      examples:
        - enabled: true
          balance: 260
          monthly_grant: 200
          monthly_grant_remaining: 160
          purchased_balance: 100
          renews_at: '2026-12-01T00:00:00+00:00'
          costs:
            keyword_run: 100
            keyword_chat_research: 10
            audit_rewrite: 100
      properties:
        enabled:
          type: boolean
          description: >-
            False while the wallet is turned off on this deployment; balance
            then reports the remaining keyword credits of the period.
        balance:
          type: integer
          minimum: 0
          description: Credits that can be spent now.
        monthly_grant:
          type: integer
          minimum: 0
          description: Grant of the plan for the running period.
        monthly_grant_remaining:
          type: integer
          minimum: 0
        purchased_balance:
          type: integer
          minimum: 0
          description: Part of the balance that never expires.
        renews_at:
          type:
            - string
            - 'null'
          format: date-time
          description: End of the running period.
        costs:
          type: object
          description: Price in credits of each paid action, by action key.
          additionalProperties:
            type: integer
            minimum: 0
    Pagination:
      type: object
      additionalProperties: false
      required:
        - limit
        - has_more
        - next_cursor
      properties:
        limit:
          type: integer
          minimum: 1
          maximum: 100
        has_more:
          type: boolean
        next_cursor:
          type:
            - string
            - 'null'
    ProductCatalogMeta:
      type: object
      additionalProperties: false
      description: Catalog summary returned by list_products only.
      required:
        - available_count
        - enriched_count
        - truncated
      properties:
        available_count:
          type: integer
          minimum: 0
          description: Usable products in the current catalog snapshot.
        enriched_count:
          type: integer
          minimum: 0
          description: Usable products with page evidence (description or image).
        truncated:
          type: boolean
          description: The latest discovery stopped at the configured catalog size.
  securitySchemes:
    OAuth2:
      type: oauth2
      description: |
        Authorization-code grant with PKCE S256, exact scopes, explicit resource
        audience and a persisted consent grant. Obtain endpoint URLs from server
        discovery in the target environment. Refresh tokens remain client-bound.
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          refreshUrl: /oauth/token
          scopes:
            profiles:read: Read authorized profiles and CMS capabilities.
            quotas:read: Read business quotas.
            keywords:read: Read existing keyword suggestions.
            geo:read: Read existing GEO analyses.
            articles:read: Read articles and generation results.
            articles:write: Edit allowed local article fields.
            articles:generate: Generate articles.
            articles:delete: Delete eligible local articles.
            calendar:read: Read calendar and slots.
            calendar:write: Manage calendar and slots.
            articles:publish: Schedule and manage CMS publication.
            products:read: Read the product catalog.
            analytics:read: Read Search Console and AI traffic analytics.
            settings:read: Read site, article, visual and YouTube settings.
            settings:write: >-
              Change site, business, competitor, article, visual and YouTube
              settings. Some changes queue asynchronous regeneration or
              synchronization.
            keywords:generate: >-
              Run keyword research and keyword generation runs. Spends the
              site's AI credits.
            audit:read: Read the site audit, its pages, their issues and the fixes.
            audit:write: >-
              Launch audits and page re-checks, create, apply and restore audit
              fixes and rewrites. Spends the site's AI credits and writes to the
              connected CMS.
            products:write: Request a refresh of the product catalog.
            geo:write: Create, edit and delete the AI visibility prompts of the site.
            backlinks:read: Read the backlink exchange state, credits and quests.
            backlinks:write: Turn the backlink exchange on or off and submit quests.
            billing:read: Read the subscription and the invoices of the site.
    PersonalAPIKey:
      type: http
      scheme: bearer
      bearerFormat: Personal API key
      description: >
        Send the one-time personal API key in Authorization: Bearer. Exact
        scopes,

        explicit profiles, expiry, revocation and transport are verified
        server-side.

        This is not an OAuth access token or a browser session.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.