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

# Project counts by category

> Get the number of projects in each category (e.g., Forestry, Renewable Energy,
    Energy Efficiency, Agriculture, etc.).

    Returns one entry per category with the distinct project count. Useful for
    pie charts or category breakdown visualizations.

    **Filters:** All standard project filters apply, allowing you to see category
    distribution for a specific registry, country, or status.



## OpenAPI

````yaml https://api.vcm.fyi/v1/openapi.json get /v1/charts/projects_by_category
openapi: 3.1.0
info:
  title: VCM.fyi API
  version: 1.0.0
  description: >

    # VCM.fyi API


    Programmatic access to carbon market intelligence — covering

    11,000+ carbon credit projects across 6 major registries (Verra, Gold
    Standard,

    CAR, ACR, Isometric, Puro Earth).


    ## Resources


    | Resource | Description |

    |---|---|

    | **Projects** | Search, filter, and retrieve carbon credit project metadata
    |

    | **Credits** | Individual credit transactions (issuances, retirements,
    cancellations) |

    | **Buyers** | Aggregated buyer intelligence from retirement transaction
    data |

    | **Charts** | Pre-aggregated chart data for visualizations |

    | **Countries** | Country-level carbon market policy intelligence (Article
    6, CORSIA, carbon pricing) |

    | **Forensics** | AI-generated project risk analysis from weekly news
    scanning |

    | **Proponent Forensics** | Developer/proponent-level risk ratings and due
    diligence |

    | **Satellite** | Forest integrity and deforestation metrics |

    | **Supply & Demand** | Aggregated issuance vs. retirement volumes over time
    |

    | **API Keys** | Manage your API keys and view usage statistics |


    ## Authentication


    All endpoints require an API key passed in the `X-API-KEY` header:


    ```bash

    curl -H "X-API-KEY: vcm_live_your_key_here" https://api.vcm.fyi/v1/projects/

    ```


    Get your API key at
    [app.vcm.fyi/settings/api](https://app.vcm.fyi/settings/api).


    ## Rate Limits


    | Plan | Requests/min | Monthly Calls |

    |------|-------------|---------------|

    | Pro | 300 | 100,000 |

    | Enterprise | 1,000 | Unlimited |


    Rate limit headers are included in every response:

    - `X-RateLimit-Limit` — Your limit per minute

    - `X-RateLimit-Remaining` — Remaining requests in current window

    - `X-RateLimit-Reset` — Unix timestamp when the window resets


    ## Pagination


    List endpoints return paginated results:


    ```json

    {
      "pagination": {
        "total_entries": 11234,
        "current_page": 1,
        "total_pages": 113,
        "next_page": "/v1/projects/?current_page=2&per_page=100"
      },
      "data": [...]
    }

    ```
  contact:
    name: VCM.fyi Support
    email: support@vcm.fyi
    url: https://vcm.fyi
  termsOfService: https://vcm.fyi/terms
  x-logo:
    url: https://app.vcm.fyi/logo.svg
    altText: VCM.fyi
servers:
  - url: https://vcm-fyi-api.fly.dev
    description: Production
security: []
tags:
  - name: API Keys
    description: Create, list, revoke your API keys and view usage statistics.
  - name: Buyers
    description: >-
      Aggregated buyer intelligence derived from retirement transactions.
      Includes volume metrics, activity flags, category/country breakdowns, and
      analytics.
  - name: Charts
    description: >-
      Pre-aggregated chart data for visualizations: projects by listing date,
      credits by transaction date, category breakdowns, credit histograms, and
      top buyers.
  - name: Countries
    description: >-
      Country-level carbon market policy intelligence covering Article 6 status,
      CORSIA eligibility, carbon pricing, VCM regulation, and AI-generated
      policy summaries.
  - name: Credits
    description: >-
      Query individual credit transactions — issuances, retirements, and
      cancellations — with quantity, vintage, date, and beneficiary details.
  - name: Forensics
    description: >-
      AI-generated project risk analysis from weekly scanning of 100+ news
      sources. Includes entries, memos, weekly diffs, and legacy v1 endpoints.
  - name: Projects
    description: >-
      Search, filter, and retrieve metadata for 11,000+ carbon credit projects
      across Verra, Gold Standard, CAR, ACR, Isometric, and Puro Earth.
  - name: Proponent Forensics
    description: >-
      Developer/proponent-level risk ratings and due diligence analysis with
      governance, financial, legal, social, and institutional risk pillar
      scores.
  - name: Satellite
    description: >-
      Forest integrity and deforestation metrics from Global Forest Watch,
      including tree cover loss, GLAD alerts, fire alerts, and project boundary
      GeoJSON.
  - name: Supply & Demand
    description: >-
      Aggregated issuance (supply) vs. retirement (demand) volumes over time,
      with monthly, quarterly, or yearly aggregation.
paths:
  /v1/charts/projects_by_category:
    get:
      tags:
        - Charts
      summary: Project counts by category
      description: >-
        Get the number of projects in each category (e.g., Forestry, Renewable
        Energy,
            Energy Efficiency, Agriculture, etc.).

            Returns one entry per category with the distinct project count. Useful for
            pie charts or category breakdown visualizations.

            **Filters:** All standard project filters apply, allowing you to see category
            distribution for a specific registry, country, or status.
      operationId: get_projects_by_category_v1_charts_projects_by_category_get
      parameters:
        - name: search
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Case insensitive search string. Currently searches on `project_id`
              and `name` fields only.
            title: Search
          description: >-
            Case insensitive search string. Currently searches on `project_id`
            and `name` fields only.
        - name: current_page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            description: Page number
            default: 1
            title: Current Page
          description: Page number
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
            maximum: 200
            minimum: 1
            description: Items per page
            default: 100
            title: Per Page
          description: Items per page
        - name: registry
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  enum:
                    - verra
                    - gold-standard
                    - american-carbon-registry
                    - climate-action-reserve
                    - art-trees
                    - isometric
                    - puro-earth
                    - plan-vivo
                    - none
                  type: string
              - type: 'null'
            description: Registry name
            title: Registry
          description: Registry name
        - name: country
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Country name
            title: Country
          description: Country name
        - name: protocol
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Protocol name
            title: Protocol
          description: Protocol name
        - name: category
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Category name
            title: Category
          description: Category name
        - name: is_compliance
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            description: Whether project is an ARB project
            title: Is Compliance
          description: Whether project is an ARB project
        - name: listed_at_from
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: string
                format: date
              - type: 'null'
            description: 'Format: YYYY-MM-DD'
            title: Listed At From
          description: 'Format: YYYY-MM-DD'
        - name: listed_at_to
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: string
                format: date
              - type: 'null'
            description: 'Format: YYYY-MM-DD'
            title: Listed At To
          description: 'Format: YYYY-MM-DD'
        - name: issued_min
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: Minimum number of issued credits
            title: Issued Min
          description: Minimum number of issued credits
        - name: issued_max
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: Maximum number of issued credits
            title: Issued Max
          description: Maximum number of issued credits
        - name: retired_min
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: Minimum number of retired credits
            title: Retired Min
          description: Minimum number of retired credits
        - name: retired_max
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: Maximum number of retired credits
            title: Retired Max
          description: Maximum number of retired credits
        - name: project_type
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: 'Project type '
            title: Project Type
          description: 'Project type '
        - name: proponent
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Project proponent/developer name
            title: Proponent
          description: Project proponent/developer name
        - name: sdg_goals
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: integer
                type: array
              - type: 'null'
            description: >-
              UN SDG goals (1-17). Multiple values = AND filter (must have ALL
              selected goals)
            title: Sdg Goals
          description: >-
            UN SDG goals (1-17). Multiple values = AND filter (must have ALL
            selected goals)
        - name: certifications
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Specific certification labels (e.g., ccb-gold,
              ccb-biodiversity-gold, corsia). Multiple values = OR filter
            title: Certifications
          description: >-
            Specific certification labels (e.g., ccb-gold,
            ccb-biodiversity-gold, corsia). Multiple values = OR filter
        - name: corc_durability
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Puro.earth CORC durability (100+ or 1000+). Multiple values = OR
              filter
            title: Corc Durability
          description: >-
            Puro.earth CORC durability (100+ or 1000+). Multiple values = OR
            filter
        - name: has_ccb
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            title: Has Ccb
            description: Has CCB (Climate, Community & Biodiversity) certification
          description: Has CCB (Climate, Community & Biodiversity) certification
        - name: has_icvcm_ccp
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            title: Has Icvcm Ccp
            description: Has ICVCM Core Carbon Principles certification
          description: Has ICVCM Core Carbon Principles certification
        - name: has_corsia
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            title: Has Corsia
            description: CORSIA eligible
          description: CORSIA eligible
        - name: has_sdvista
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            title: Has Sdvista
            description: Has SD VISta certification
          description: Has SD VISta certification
        - name: has_social_carbon
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            title: Has Social Carbon
            description: Has Social Carbon certification
          description: Has Social Carbon certification
        - name: article6_authorized
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            title: Article6 Authorized
            description: Authorized under Paris Agreement Article 6
          description: Authorized under Paris Agreement Article 6
        - name: article6_authorization_types
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Article 6 authorization types: NDC Use, Intl mitigation purposes,
              Other purposes
            title: Article6 Authorization Types
          description: >-
            Article 6 authorization types: NDC Use, Intl mitigation purposes,
            Other purposes
      responses:
        '200':
          description: Project counts grouped by category
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedProjectCounts'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    PaginatedProjectCounts:
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
        data:
          anyOf:
            - items:
                $ref: '#/components/schemas/ProjectCounts'
              type: array
            - items:
                additionalProperties: true
                type: object
              type: array
          title: Data
      type: object
      required:
        - pagination
        - data
      title: PaginatedProjectCounts
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Pagination:
      properties:
        total_entries:
          type: integer
          title: Total Entries
        current_page:
          type: integer
          title: Current Page
        total_pages:
          type: integer
          title: Total Pages
        next_page:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Page
      type: object
      required:
        - total_entries
        - current_page
        - total_pages
      title: Pagination
    ProjectCounts:
      properties:
        category:
          type: string
          title: Category
        value:
          type: integer
          title: Value
      type: object
      required:
        - category
        - value
      title: ProjectCounts
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-KEY

````