GitLab Plan limits API

openapi: 3.2.0
info:
  title: GitLab REST Plan limits API
  description: GitLab REST API used to interact with a GitLab installation.
  termsOfService: https://handbook.gitlab.com/handbook/legal/api-terms/
  version: '19.6'
  license:
    name: CC BY-SA 4.0
    url: https://gitlab.com/gitlab-org/gitlab/-/blob/master/LICENSE
    x-gitlab-description: The license applies to the OpenAPI specification document itself. For terms governing use of the GitLab API, see the termsOfService field.
servers:
- url: https://{hostname}
  description: GitLab REST API
  variables:
    hostname:
      default: gitlab.com
      description: Your GitLab instance hostname
security:
- http: []
- oauth2: []
- apiKey: []
tags:
- name: Plan limits
  description: 'Use this API to retrieve and change the application limits of a subscription plan.


    The available plans depend on the GitLab edition. In the Community Edition, only the `default` plan

    exists. The Enterprise Edition has additional plans.


    These endpoints require administrator access to the instance.'
  x-displayName: Plan limits
  externalDocs:
    url: https://docs.gitlab.com/api/plan_limits/
paths:
  /api/v4/application/plan_limits:
    get:
      operationId: getApiV4ApplicationPlanLimits
      summary: Get current plan limits
      description: List the current limits of a plan on the GitLab instance.
      tags:
      - Plan limits
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesPlanLimit'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '400':
          description: Bad Request
      parameters:
      - name: plan_name
        required: false
        description: Name of the plan to get the limits from.
        schema:
          type: string
          enum:
          - default
          - free
          - bronze
          - silver
          - premium
          - gold
          - ultimate
          - ultimate_trial
          - ultimate_trial_paid_customer
          - premium_trial
          - opensource
          default: default
        in: query
    put:
      operationId: putApiV4ApplicationPlanLimits
      summary: Change plan limits
      description: Modify the limits of a plan on the GitLab instance.
      tags:
      - Plan limits
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesPlanLimit'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/putApiV4ApplicationPlanLimitsRequest'
components:
  schemas:
    putApiV4ApplicationPlanLimitsRequest:
      type: object
      properties:
        plan_name:
          type: string
          enum:
          - default
          - free
          - bronze
          - silver
          - premium
          - gold
          - ultimate
          - ultimate_trial
          - ultimate_trial_paid_customer
          - premium_trial
          - opensource
          description: Name of the plan to update.
          minLength: 1
        cargo_max_file_size:
          type:
          - integer
          - 'null'
          description: Maximum Cargo package file size in bytes. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/33060) in GitLab 19.3.
        ci_instance_level_variables:
          type:
          - integer
          - 'null'
          description: Maximum number of instance-level CI/CD variables that can be defined.
        ci_pipeline_size:
          type:
          - integer
          - 'null'
          description: Maximum number of jobs in a single pipeline.
        ci_active_jobs:
          type:
          - integer
          - 'null'
          description: Total number of jobs in currently active pipelines.
        ci_project_subscriptions:
          type:
          - integer
          - 'null'
          description: Maximum number of pipeline subscriptions to and from a project.
        ci_pipeline_schedules:
          type:
          - integer
          - 'null'
          description: Maximum number of pipeline schedules.
        ci_needs_size_limit:
          type:
          - integer
          - 'null'
          description: Maximum number of `needs` dependencies that a job can have.
        ci_registered_group_runners:
          type:
          - integer
          - 'null'
          description: Maximum number of runners created or active in a group during the past seven days.
        ci_registered_project_runners:
          type:
          - integer
          - 'null'
          description: Maximum number of runners created or active in a project during the past seven days.
        conan_max_file_size:
          type:
          - integer
          - 'null'
          description: Maximum Conan package file size in bytes.
        dotenv_size:
          type:
          - integer
          - 'null'
          description: Maximum size of a dotenv artifact in bytes. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/432529) in GitLab 17.1.
        dotenv_variables:
          type:
          - integer
          - 'null'
          description: Maximum number of variables in a dotenv artifact. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/432529) in GitLab 17.1.
        enforcement_limit:
          type:
          - integer
          - 'null'
          description: Maximum storage size for root namespace limit enforcement, in MiB.
        generic_packages_max_file_size:
          type:
          - integer
          - 'null'
          description: Maximum generic package file size in bytes.
        helm_max_file_size:
          type:
          - integer
          - 'null'
          description: Maximum Helm chart file size in bytes.
        maven_max_file_size:
          type:
          - integer
          - 'null'
          description: Maximum Maven package file size in bytes.
        notification_limit:
          type:
          - integer
          - 'null'
          description: Maximum storage size for root namespace limit notifications, in MiB.
        npm_max_file_size:
          type:
          - integer
          - 'null'
          description: Maximum npm package file size in bytes.
        nuget_max_file_size:
          type:
          - integer
          - 'null'
          description: Maximum NuGet package file size in bytes.
        pypi_max_file_size:
          type:
          - integer
          - 'null'
          description: Maximum PyPI package file size in bytes.
        service_desk_outbound_emails_per_hour:
          type:
          - integer
          - 'null'
          description: Maximum number of outbound Service Desk emails per hour, per top-level namespace. Set to `0` for unlimited. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/253087) in GitLab 19.4.
        service_desk_outbound_emails_per_day:
          type:
          - integer
          - 'null'
          description: Maximum number of outbound Service Desk emails per day, per top-level namespace. Set to `0` for unlimited. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/253087) in GitLab 19.4.
        terraform_module_max_file_size:
          type:
          - integer
          - 'null'
          description: Maximum Terraform module package file size in bytes.
        storage_size_limit:
          type:
          - integer
          - 'null'
          description: Maximum storage size for the root namespace, in MiB.
        pipeline_hierarchy_size:
          type:
          - integer
          - 'null'
          description: Maximum number of downstream pipelines in a pipeline's hierarchy tree. The default is `1000`. Higher values are not recommended.
        web_hook_calls:
          type:
          - integer
          - 'null'
          description: Maximum number of times a webhook can be called per minute, per top-level namespace. Set to `0` for unlimited. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/571738) in GitLab 18.5.
        web_hook_calls_low:
          type:
          - integer
          - 'null'
          description: Maximum number of times a webhook can be called per minute, per top-level namespace. Set to `0` for unlimited. GitLab.com only.
        web_hook_calls_mid:
          type:
          - integer
          - 'null'
          description: Maximum number of times a webhook can be called per minute, per top-level namespace. Set to `0` for unlimited. GitLab.com only.
        max_pipelines_per_merge_train:
          type:
          - integer
          - 'null'
          description: Maximum number of parallel pipelines per merge train. The default is `20` and the minimum is `1`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/374188) in GitLab 19.0.
      required:
      - plan_name
    APIEntitiesPlanLimit:
      type: object
      properties:
        cargo_max_file_size:
          type: integer
          example: 5368709120
        ci_instance_level_variables:
          type: integer
          example: 25
        ci_pipeline_size:
          type: integer
          example: 0
        ci_active_jobs:
          type: integer
          example: 0
        ci_project_subscriptions:
          type: integer
          example: 2
        ci_pipeline_schedules:
          type: integer
          example: 10
        ci_needs_size_limit:
          type: integer
          example: 50
        ci_registered_group_runners:
          type: integer
          example: 1000
        ci_registered_project_runners:
          type: integer
          example: 1000
        conan_max_file_size:
          type: integer
          example: 3221225472
        dotenv_variables:
          type: integer
          example: 20
        dotenv_size:
          type: integer
          example: 5120
        enforcement_limit:
          type: integer
          example: 15000
        generic_packages_max_file_size:
          type: integer
          example: 5368709120
        helm_max_file_size:
          type: integer
          example: 5242880
        limits_history:
          type: object
          example:
            enforcement_limit:
            - timestamp: 1686909124
              user_id: 1
              username: x
              value: 5
            notification_limit:
            - timestamp: 1686909124
              user_id: 2
              username: y
              value: 7
        maven_max_file_size:
          type: integer
          example: 3221225472
        notification_limit:
          type: integer
          example: 15000
        npm_max_file_size:
          type: integer
          example: 524288000
        nuget_max_file_size:
          type: integer
          example: 524288000
        pipeline_hierarchy_size:
          type: integer
          example: 1000
        pypi_max_file_size:
          type: integer
          example: 3221225472
        service_desk_outbound_emails_per_hour:
          type: integer
          example: 100
        service_desk_outbound_emails_per_day:
          type: integer
          example: 700
        terraform_module_max_file_size:
          type: integer
          example: 1073741824
        storage_size_limit:
          type: integer
          example: 15000
        web_hook_calls:
          type: integer
          example: 500
        web_hook_calls_low:
          type: integer
          example: 500
        web_hook_calls_mid:
          type: integer
          example: 500
        max_pipelines_per_merge_train:
          type: integer
          example: 20
  securitySchemes:
    http:
      type: http
      scheme: bearer
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://gitlab.com/oauth/authorize
          tokenUrl: https://gitlab.com/oauth/token
          refreshUrl: https://gitlab.com/oauth/token
          scopes:
            api: Grants complete read/write access to the API, including all groups and projects, the container registry, the dependency proxy, and the package registry.
            read_api: Grants read access to the API, including all groups and projects, the container registry, and the package registry.
            read_user: Grants read-only access to your profile through the /user API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under /users.
            create_runner: Grants create access to the runners.
            manage_runner: Grants access to manage the runners.
            k8s_proxy: Grants permission to perform Kubernetes API calls using the agent for Kubernetes.
            self_rotate: Grants permission for token to rotate itself.
            mcp: Grants read-write access to remote Model Context Protocol (MCP) server for tools execution.
            mcp_orbit: Grants access to the Orbit Knowledge Graph MCP server for graph queries and schema retrieval.
    apiKey:
      type: apiKey
      name: PRIVATE-TOKEN
      in: header