> ## 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 invoices

> The team's invoices, newest first, with each invoice's charges per price. Draft invoices are not listed; void ones are, with `status: void`. A billing period can have several invoices: `subscription_threshold` invoices bill usage mid-period and the `subscription_cycle` invoice closes it. Follow `pagination.next_page_token` until it is null; a page can hold fewer than `page_size` invoices and still have a next page. 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/invoices
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/invoices:
    get:
      tags:
        - Billing Invoices
      summary: List invoices
      description: >-
        The team's invoices, newest first, with each invoice's charges per
        price. Draft invoices are not listed; void ones are, with `status:
        void`. A billing period can have several invoices:
        `subscription_threshold` invoices bill usage mid-period and the
        `subscription_cycle` invoice closes it. Follow
        `pagination.next_page_token` until it is null; a page can hold fewer
        than `page_size` invoices and still have a next page. Scale plan only:
        other plans get an empty list and a `message`.
      operationId: listInvoices
      parameters:
        - schema:
            minimum: 1
            maximum: 100
            type: integer
          in: query
          name: page_size
          required: false
          description: Maximum invoices to return. Defaults to 20.
        - 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:
                        id:
                          type: string
                        number:
                          anyOf:
                            - type: string
                            - type: 'null'
                        status:
                          description: >-
                            `open`, `paid`, `uncollectible` or `void`. A void
                            invoice is not owed. Drafts are not listed.
                          type: string
                        billing_reason:
                          anyOf:
                            - description: >-
                                Why Stripe cut the invoice.
                                `subscription_threshold` invoices bill usage
                                mid-period once it crosses the billing
                                threshold; `subscription_cycle` closes the
                                period.
                              type: string
                            - type: 'null'
                        created_at:
                          format: date-time
                          type: string
                        period_start:
                          format: date-time
                          type: string
                        period_end:
                          format: date-time
                          type: string
                        currency:
                          type: string
                        subtotal_cents:
                          type: integer
                        discount_cents:
                          type: integer
                        credits_applied_cents:
                          type: integer
                        total_cents:
                          type: integer
                        pdf_url:
                          anyOf:
                            - type: string
                            - type: 'null'
                        line_items:
                          type: array
                          items:
                            type: object
                            properties:
                              price_name:
                                description: Stable internal price name.
                                type: string
                              display_name:
                                type: string
                              product:
                                description: >-
                                  Product key: `turbo`, `mirror`, `subgraphs`,
                                  `edge`, `hostedPostgres`, `feeds`, `compose`,
                                  `boost` or `other`.
                                type: string
                              quantity:
                                description: Billed quantity, tiers summed.
                                type: number
                              amount_cents:
                                description: >-
                                  Gross charge in USD cents, before discounts
                                  and credits.
                                type: integer
                            required:
                              - price_name
                              - display_name
                              - product
                              - quantity
                              - amount_cents
                      required:
                        - id
                        - number
                        - status
                        - billing_reason
                        - created_at
                        - period_start
                        - period_end
                        - currency
                        - subtotal_cents
                        - discount_cents
                        - credits_applied_cents
                        - total_cents
                        - pdf_url
                        - line_items
                  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

- [List costs per billing period](https://docs.goldsky.com/api-reference/billing-costs/list-costs-per-billing-period.md)
- [List webhooks](https://docs.goldsky.com/api-reference/subgraph-webhooks/list-webhooks.md)
- [List pipelines](https://docs.goldsky.com/api-reference/pipelines/list-pipelines.md)
- [List subgraphs](https://docs.goldsky.com/api-reference/subgraphs/list-subgraphs.md)
- [List feeds](https://docs.goldsky.com/api-reference/feed-catalog/list-feeds.md)
