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

# List costs per billing period

> Gross cost per billing period, broken down by product and price, newest period first. The first page leads with the current period (`is_current: true`): `invoiced_cents` is what threshold invoices have already billed, `accruing_cents` what the next invoice will. Stripe updates it about once an hour. Each closed period sums every invoice in the period that is neither draft nor void. Amounts are before discounts and credits, which apply to whole invoices: see `GET /billing/invoices` for what was charged. Follow `pagination.next_page_token` until it is null. Scale plan only: other plans get an empty list and a `message`.



## OpenAPI

````yaml https://api.goldsky.com/api/v1/docs/openapi.json get /billing/costs
openapi: 3.1.0
info:
  title: Goldsky API
  description: >-
    REST API for managing Goldsky resources — projects, pipelines, subgraphs,
    Edge endpoints, and Feeds keys and usage — and for reading your billing.
    Create, deploy, monitor, and manage them programmatically.


    For guides and reference, see the [Goldsky
    documentation](https://docs.goldsky.com) — including
    [Subgraphs](https://docs.goldsky.com/subgraphs/introduction) and
    [Pipelines](https://docs.goldsky.com/mirror/introduction).


    ## Authentication


    Every request carries an API token as a bearer token:


    ```

    Authorization: Bearer <token>

    ```


    Create one on the [API Keys
    page](https://app.goldsky.com/dashboard/settings/api-keys) of the Goldsky
    dashboard. A token is scoped to the project it was created in, so the
    project is never part of a request path.


    Read operations need the Viewer role; writes need Editor.


    The Feeds data itself — wallet transfers and balances — is served from
    `https://edge.goldsky.com/data` with a Data API key, and documented in its
    own reference:
    [edge.goldsky.com/data/openapi.json](https://edge.goldsky.com/data/openapi.json).


    ## Errors


    Errors are [RFC 9457 problem
    details](https://www.rfc-editor.org/rfc/rfc9457) served as
    `application/problem+json`:


    ```json

    {
      "type": "https://api.goldsky.com/api/errors/subgraph-not-found",
      "title": "Subgraph not found",
      "status": 404,
      "detail": "No subgraph named 'my-subgraph' exists in this project.",
      "instance": "/api/v1/subgraphs/my-subgraph"
    }

    ```


    Branch on `type`, not on `title` or `detail` — the URI is stable, the prose
    is not. Every `type` dereferences to a human-readable page describing the
    cause and the fix; the full list lives at
    [api.goldsky.com/api/errors](https://api.goldsky.com/api/errors). Validation
    failures (400) add an `errors` array naming each offending field.


    ## Pagination


    List endpoints that can return unbounded results — pipelines, subgraphs,
    invoices and billing costs — page with `page_size` and `page_token`:


    ```

    GET /api/v1/subgraphs?page_size=50

    GET /api/v1/subgraphs?page_size=50&page_token=<pagination.next_page_token>

    ```


    Keep following `pagination.next_page_token` until it comes back `null`. A
    page can hold fewer than `page_size` items and still have a next page, so
    treat a short page as "keep going", not as the end.
  version: 1.8.0
  contact:
    name: Goldsky Support
    email: support@goldsky.com
    url: https://docs.goldsky.com
servers:
  - url: /api/v1
    description: Current environment
security:
  - BearerAuth: []
tags:
  - name: Pipelines
    x-displayName: Create & manage
    description: >-
      Create, read, and delete pipelines. A pipeline is identified by its name
      within the project.
  - name: Pipeline Authoring
    x-displayName: Validate & preview
    description: >-
      Check a pipeline definition and see what it would produce, before creating
      anything. Neither endpoint touches an existing pipeline.
  - name: Pipeline Lifecycle
    x-displayName: Lifecycle
    description: Pause, resume, and restart a running pipeline.
  - name: Pipeline Status
    x-displayName: Status
    description: Query pipeline runtime status and per-source progress state.
  - name: Pipeline Logs
    x-displayName: Logs
    description: Retrieve pipeline execution logs and error counts.
  - name: Subgraphs
    x-displayName: Browse
    description: >-
      Read subgraphs and their versions. A subgraph is identified by
      `name`/`version`.
  - name: Subgraph Deployments
    x-displayName: Deployments
    description: >-
      Deploy a compiled subgraph bundle as a new version, or remove a deployed
      one.
  - name: Subgraph Tags
    x-displayName: Tags
    description: >-
      Point a stable alias — `production`, say — at a specific version, so
      consumers keep one URL across deploys.
  - name: Subgraph Lifecycle
    x-displayName: Lifecycle
    description: Pause and resume indexing, and update the settings of a deployed version.
  - name: Subgraph Logs
    x-displayName: Logs
    description: Retrieve subgraph indexing logs.
  - name: Subgraph Webhooks
    x-displayName: Webhooks
    description: >-
      Stream row-level changes to a subgraph entity out to a URL. Webhooks are
      project-scoped and each one targets a single entity of a single subgraph
      version.
  - name: Edge Endpoints
    x-displayName: Create & manage
    description: >-
      Create and manage Edge endpoints — RPC and Data — including rate limits
      and allowed domains.
  - name: Edge Lifecycle
    x-displayName: Lifecycle
    description: >-
      Pause and resume an endpoint. A paused endpoint rejects traffic but keeps
      its configuration and key.
  - name: Edge API Keys
    x-displayName: API keys
    description: Reveal the API key an Edge endpoint serves traffic under.
  - name: Edge Metrics
    x-displayName: Metrics
    description: Request volume and error rates for an Edge endpoint.
  - name: Boost
    x-displayName: Endpoint
    description: >-
      Read and update the project's Boost: a cache-first proxy for EVM JSON-RPC
      reads, backed by your own provider upstreams. One Boost per project. Free
      for verified organizations: a team with a member on a business email
      domain (not a free mailbox provider) qualifies automatically.
  - name: Boost Lifecycle
    x-displayName: Lifecycle
    description: >-
      Enable and disable the project's Boost. A disabled Boost refuses traffic
      but keeps its chains, upstreams, and key.
  - name: Boost API Keys
    x-displayName: API key
    description: Reveal the API key the Boost serves traffic under.
  - name: Boost Chains
    x-displayName: Chains
    description: >-
      List the chains Boost can cache, and switch a chain on or off or override
      its timeouts on this Boost.
  - name: Boost Providers
    x-displayName: Provider accounts
    description: >-
      Connect a provider account (Alchemy or QuickNode) and let Boost create and
      register its endpoints for you, instead of pasting URLs one chain at a
      time.
  - name: Boost Upstreams
    x-displayName: Upstreams
    description: >-
      The provider URLs Boost forwards to, one active per chain with fallbacks.
      Validate a URL, add or remove an upstream, replace its URL, fail over to
      another, or tune its settings. Upstreams are addressed by `{chain, id}` in
      the request body.
  - name: Boost Metrics
    x-displayName: Metrics
    description: >-
      Cache hit rate, latency, provider calls, credit savings, and the
      per-request history for a Boost.
  - name: Feed Catalog
    x-displayName: Catalog & API key
    description: >-
      List the feeds Goldsky offers and when the project first used each, and
      get or create the project's Feeds key (a Data API key named `feeds`) every
      feed authenticates with; rotate it with `POST /api/v1/feeds/key/rotate`.
  - name: Feed Syncs
    x-displayName: Syncs
    description: >-
      Stream a wallet feed into your own database or webhook: create a sync, add
      and remove the wallets, tokens and chains it covers, backfill history,
      follow its status, and delete it. Syncs exist for `wallets/balances` and
      `wallets/transfers`.
  - name: Feed Logs
    x-displayName: Request logs
    description: >-
      Every request the project sent a feed: when, which path, whether it
      succeeded, and how long it took. Kept for 30 days.
  - name: Projects
    x-displayName: Create
    description: >-
      Create projects in a team you own or administer. Every other resource
      lives in a project, and a token only reaches the project it was created
      in.
  - name: Billing Invoices
    x-displayName: Invoices
    description: >-
      Read the team's invoices with their charges per price. Read-only; needs
      the Viewer role. Scale plan only.
  - name: Billing Costs
    x-displayName: Costs
    description: >-
      Read cost per product for each billing period, and per day for the current
      one. Read-only; needs the Viewer role. Scale plan only.
  - name: Catalogs
    x-displayName: Catalogs
    description: >-
      What Goldsky supports: chains you can index a subgraph on, and the
      networks and datasets an Edge endpoint can be pointed at.
      Unauthenticated-safe reads that never change per project.
paths:
  /billing/costs:
    get:
      tags:
        - Billing Costs
      summary: List costs per billing period
      description: >-
        Gross cost per billing period, broken down by product and price, newest
        period first. The first page leads with the current period (`is_current:
        true`): `invoiced_cents` is what threshold invoices have already billed,
        `accruing_cents` what the next invoice will. Stripe updates it about
        once an hour. Each closed period sums every invoice in the period that
        is neither draft nor void. Amounts are before discounts and credits,
        which apply to whole invoices: see `GET /billing/invoices` for what was
        charged. Follow `pagination.next_page_token` until it is null. Scale
        plan only: other plans get an empty list and a `message`.
      operationId: listBillingCosts
      parameters:
        - schema:
            minimum: 1
            maximum: 24
            type: integer
          in: query
          name: page_size
          required: false
          description: Maximum closed billing periods to return. Defaults to 6.
        - schema:
            type: string
          in: query
          name: page_token
          required: false
          description: >-
            The `pagination.next_page_token` from a previous response. Omit for
            the first page.
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        period_start:
                          format: date-time
                          type: string
                        period_end:
                          anyOf:
                            - format: date-time
                              type: string
                            - type: 'null'
                        is_current:
                          type: boolean
                        amount_cents:
                          description: >-
                            Gross cost in USD cents, before discounts and
                            credits.
                          type: integer
                        invoiced_cents:
                          description: Part of `amount_cents` already invoiced.
                          type: integer
                        accruing_cents:
                          description: >-
                            Part of `amount_cents` not yet invoiced. Zero for a
                            closed period.
                          type: integer
                        products:
                          type: array
                          items:
                            type: object
                            properties:
                              product:
                                description: >-
                                  Product key: `turbo`, `mirror`, `subgraphs`,
                                  `edge`, `hostedPostgres`, `feeds`, `compose`,
                                  `boost` or `other`.
                                type: string
                              display_name:
                                type: string
                              amount_cents:
                                description: >-
                                  Gross cost in USD cents, before discounts and
                                  credits.
                                type: integer
                              invoiced_cents:
                                description: Part of `amount_cents` already invoiced.
                                type: integer
                              accruing_cents:
                                description: >-
                                  Part of `amount_cents` not yet invoiced. Zero
                                  for a closed period.
                                type: integer
                              prices:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    price_name:
                                      type: string
                                    display_name:
                                      type: string
                                    quantity:
                                      type: number
                                    amount_cents:
                                      description: >-
                                        Gross cost in USD cents, before
                                        discounts and credits.
                                      type: integer
                                    invoiced_cents:
                                      description: Part of `amount_cents` already invoiced.
                                      type: integer
                                    accruing_cents:
                                      description: >-
                                        Part of `amount_cents` not yet invoiced.
                                        Zero for a closed period.
                                      type: integer
                                  required:
                                    - price_name
                                    - display_name
                                    - quantity
                                    - amount_cents
                                    - invoiced_cents
                                    - accruing_cents
                            required:
                              - product
                              - display_name
                              - amount_cents
                              - invoiced_cents
                              - accruing_cents
                              - prices
                      required:
                        - period_start
                        - period_end
                        - is_current
                        - amount_cents
                        - invoiced_cents
                        - accruing_cents
                        - products
                  pagination:
                    type: object
                    properties:
                      next_page_token:
                        anyOf:
                          - type: string
                          - type: 'null'
                      page_size:
                        type: number
                    required:
                      - next_page_token
                      - page_size
                  message:
                    description: >-
                      Set when there is nothing to return because the team is
                      not on the Scale plan.
                    type: string
                required:
                  - data
                  - pagination
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        API token generated from the [Goldsky
        Dashboard](https://app.goldsky.com/dashboard/settings/api-keys). Pass
        as: Authorization: Bearer <token>

````

## Related topics

- [Daily cost in the current billing period](https://docs.goldsky.com/api-reference/billing-costs/daily-cost-in-the-current-billing-period.md)
- [Pricing: plans, metering, and product costs](https://docs.goldsky.com/pricing/summary.md)
- [List invoices](https://docs.goldsky.com/api-reference/billing-invoices/list-invoices.md)
- [Chain head](https://docs.goldsky.com/feeds/api/chain-datasets/chain-head.md)
- [Prediction markets Balances](https://docs.goldsky.com/feeds/api/prediction-markets/balances.md)
