Cloud Foundry

Cloud Foundry App Usage Events API

App usage events are a record of changes in the usage of apps and tasks.

GitHub OpenAPI

Operations 3

GET /v3/app_usage_events List app usage events #
GET /v3/app_usage_events/{guid} Get an app usage event #
POST /v3/app_usage_events/actions/destructively_purge_all_and_reseed Purge and seed app usage events #

Documentation

📖
APIReference
https://v3-apidocs.cloudfoundry.org/
📖
Documentation
https://docs.cloudfoundry.org/
📖
Documentation
https://www.openservicebrokerapi.org/
📖
Documentation
https://github.com/cloudfoundry/app-autoscaler/blob/main/docs/user_guide.md

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/cloud-foundry/refs/heads/main/openapi/cloud-foundry-app-usage-events-api-openapi.yml

Other Resources

🔗
Source Code
https://github.com/cloudfoundry/cloud_controller_ng
🔗
Specification
https://github.com/cloudfoundry/cf-openapi
🔗
Reference
https://cloudfoundry.github.io/cf-openapi/
🔗
Specification
https://github.com/openservicebrokerapi/servicebroker
🔗
Source Code
https://github.com/cloudfoundry/app-autoscaler

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/cloud-foundry-app-usage-events-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

cloud-foundry-app-usage-events-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Cloud Foundry V3 App Usage Events API
  description: '# Welcome to the Experimental Cloud Foundry V3 API Docs!'
  version: latest
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  contact:
    name: Cloud Foundry
    url: https://www.cloudfoundry.org/
servers:
- url: https://api.example.local
  description: Cloud Foundry V3 API server
security:
- oauth:
  - cloud_controller.read
  - cloud_controller.write
tags:
- name: App Usage Events
  description: App usage events are a record of changes in the usage of apps and tasks.
paths:
  /v3/app_usage_events:
    get:
      summary: List app usage events
      description: Retrieve all app usage events.
      operationId: listAppUsageEvents
      tags:
      - App Usage Events
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      - $ref: '#/components/parameters/OrderBy'
      - name: after_guid
        in: query
        schema:
          type: string
        description: Filters out events before and including the event with the given guid
      - name: guids
        in: query
        schema:
          type: array
          items:
            type: string
        description: Comma-delimited list of usage event guids to filter by
      - $ref: '#/components/parameters/CreatedAts'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppUsageEventList'
              examples:
                default:
                  summary: default
                  value:
                    pagination:
                      total_results: 2
                      total_pages: 2
                      first:
                        href: https://api.example.org<%= path %>?page=1&per_page=1
                      last:
                        href: https://api.example.org<%= path %>?page=2&per_page=1
                      next:
                        href: https://api.example.org<%= path %>?page=2&per_page=1
                      previous: null
                    resources:
                    - guid: 123e4567-e89b-12d3-a456-426614174000
                      created_at: '2020-05-28T16:41:23Z'
                      updated_at: '2020-05-28T16:41:26Z'
                      state:
                        current: STARTED
                        previous: STOPPED
                      app:
                        guid: 123e4567-e89b-12d3-a456-426614174000
                        name: name-1982
                      process:
                        guid: 123e4567-e89b-12d3-a456-426614174000
                        type: type-1983
                      space:
                        guid: 123e4567-e89b-12d3-a456-426614174000
                        name: name-1664
                      organization:
                        guid: 123e4567-e89b-12d3-a456-426614174000
                      buildpack:
                        guid: 123e4567-e89b-12d3-a456-426614174000
                        name: label-64
                      task:
                        guid: 123e4567-e89b-12d3-a456-426614174000
                        name: name-2929
                      memory_in_mb_per_instance:
                        current: 512
                        previous: 256
                      instance_count:
                        current: 10
                        previous: 5
                      links:
                        self:
                          href: https://api.example.org/v3/app_usage_events/a595fe2f-01ff-4965-a50c-290258ab8582
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/500'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v3/app_usage_events/{guid}:
    get:
      summary: Get an app usage event
      description: Retrieve a specific app usage event.
      operationId: getAppUsageEvent
      tags:
      - App Usage Events
      parameters:
      - $ref: '#/components/parameters/Guid'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppUsageEvent'
              examples:
                default:
                  summary: default
                  value:
                    guid: 123e4567-e89b-12d3-a456-426614174000
                    created_at: '2020-05-28T16:41:23Z'
                    updated_at: '2020-05-28T16:41:26Z'
                    state:
                      current: STARTED
                      previous: STOPPED
                    app:
                      guid: 123e4567-e89b-12d3-a456-426614174000
                      name: name-1982
                    process:
                      guid: 123e4567-e89b-12d3-a456-426614174000
                      type: type-1983
                    space:
                      guid: 123e4567-e89b-12d3-a456-426614174000
                      name: name-1664
                    organization:
                      guid: 123e4567-e89b-12d3-a456-426614174000
                    buildpack:
                      guid: 123e4567-e89b-12d3-a456-426614174000
                      name: label-64
                    task:
                      guid: 123e4567-e89b-12d3-a456-426614174000
                      name: name-2929
                    memory_in_mb_per_instance:
                      current: 512
                      previous: 256
                    instance_count:
                      current: 10
                      previous: 5
                    links:
                      self:
                        href: https://api.example.org/v3/app_usage_events/a595fe2f-01ff-4965-a50c-290258ab8582
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v3/app_usage_events/actions/destructively_purge_all_and_reseed:
    post:
      summary: Purge and seed app usage events
      description: 'Destroys all existing events. Populates new usage events, one for each

        started app. All populated events will have a created_at value of

        current time. There is the potential race condition if apps are

        currently being started, stopped, or scaled. The seeded usage events

        will have the same guid as the app.'
      operationId: purgeAndSeedAppUsageEvents
      tags:
      - App Usage Events
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    Pagination:
      type: object
      properties:
        total_results:
          type: integer
          description: The total number of results available
        total_pages:
          type: integer
          description: The total number of pages available
        first:
          allOf:
          - $ref: '#/components/schemas/Link'
          - description: The first page of results
        last:
          allOf:
          - $ref: '#/components/schemas/Link'
          - description: The last page of results
        next:
          oneOf:
          - $ref: '#/components/schemas/Link'
          - type: 'null'
          description: The next page of results
        previous:
          oneOf:
          - $ref: '#/components/schemas/Link'
          - type: 'null'
          description: The previous page of results
      description: 'Pagination is a technique used to divide a large set of results into smaller, more manageable sets. This allows clients to retrieve results in smaller chunks, reducing the amount of data transferred and improving performance.

        The pagination object is a JSON object that contains information about the pagination state of the results. It includes the total number of results available, the total number of pages available, and links to the first, last, next, and previous pages of results.

        '
    Link:
      type: object
      properties:
        href:
          type: string
          description: The URL of the link
        method:
          type: string
          description: An optional field containing the HTTP method to be used when following the URL
      required:
      - href
      description: 'Each link is keyed by its type and will include a href for the URL and an optional method for links that cannot be followed using GET.

        '
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
      description: 'An error response will always return a list of error objects. Errors appear on the job resource for asynchronous operations.

        Clients should use the code and title fields for programmatically handling specific errors. The message in the detail field is subject to change over time.

        '
    AppUsageEventList:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
        resources:
          type: array
          items:
            $ref: '#/components/schemas/AppUsageEvent'
    Error:
      type: object
      properties:
        code:
          type: integer
          description: A numeric code for this error
        detail:
          type: string
          description: Detailed description of the error
        title:
          type: string
          description: Name of the error
    AppUsageEvent:
      type: object
      allOf:
      - $ref: '#/components/schemas/BaseSchema'
      properties:
        state:
          type: object
          properties:
            current:
              type: string
              description: Current state of the app that this event pertains to, if applicable
            previous:
              type:
              - string
              - 'null'
              description: Previous state of the app that this event pertains to, if applicable
        app:
          type: object
          properties:
            guid:
              type: string
              description: Unique identifier of the app that this event pertains to, if applicable
            name:
              type:
              - string
              - 'null'
              description: Name of the app that this event pertains to, if applicable
        process:
          type: object
          properties:
            guid:
              type: string
              description: Unique identifier of the process that this event pertains to, if applicable
            type:
              type: string
              description: Type of the process that this event pertains to, if applicable
        space:
          type: object
          properties:
            guid:
              type: string
              description: Unique identifier of the space that this event pertains to, if applicable
            name:
              type:
              - string
              - 'null'
              description: Name of the space that this event pertains to, if applicable
        organization:
          type: object
          properties:
            guid:
              type: string
              description: Unique identifier of the org that this event pertains to, if applicable
        buildpack:
          type: object
          properties:
            guid:
              type: string
              description: Unique identifier of the buildpack that this event pertains to, if applicable
            name:
              type:
              - string
              - 'null'
              description: Name of the buildpack that this event pertains to, if applicable
        task:
          type: object
          properties:
            guid:
              type: string
              description: Unique identifier of the task that this event pertains to, if applicable
            name:
              type:
              - string
              - 'null'
              description: Name of the task that this event pertains to, if applicable
        memory_in_mb_per_instance:
          type: object
          properties:
            current:
              type: integer
              description: Current memory in MB of the app that this event pertains to, if applicable
            previous:
              type:
              - integer
              - 'null'
              description: Previous memory in MB of the app that this event pertains to, if applicable
        instance_count:
          type: object
          properties:
            current:
              type: integer
              description: Current instance count of the app that this event pertains to, if applicable
            previous:
              type:
              - integer
              - 'null'
              description: Previous instance count of the app that this event pertains to, if applicable
      description: 'App usage events are a record of changes in the usage of apps and tasks. Examples include starting an application, scaling an application (from, say, one to three instances), and stopping an application.

        Usage events are typically used by billing and chargeback applications.'
    BaseSchema:
      type: object
      properties:
        guid:
          type: string
          format: uuid
          description: The unique identifier for the resource
        created_at:
          type: string
          format: date-time
          description: The ISO8601 compatible date and time when resource was created
        updated_at:
          type: string
          format: date-time
          description: The ISO8601 compatible date and time when resource was last updated
      description: 'A resource represents an individual object within the system, such as an app or a service. It is represented as a JSON object.

        A resource consists of several required resource fields and other attributes specific to the resource.

        See Resources and Experimental Resources for specific resources.

        '
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    UnprocessableEntity:
      description: Unprocessable Entity
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    BadGateway:
      description: Bad Gateway
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
        text/html:
          schema:
            type: string
    ServiceUnavailable:
      description: Service Unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
  parameters:
    OrderBy:
      name: order_by
      in: query
      required: false
      schema:
        type: string
      description: 'Value to sort by. Defaults to ascending; prepend with `-` to sort descending.

        '
      example: created_at
    CreatedAts:
      name: created_ats
      in: query
      required: false
      schema:
        type: string
      description: 'Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with [relational operators](#relational-operators).

        '
      example: '2021-01-01T00:00:00Z'
    PerPage:
      name: per_page
      in: query
      required: false
      schema:
        type: integer
      description: Number of results per page, valid values are 1 through 5000
      example: 50
    Page:
      name: page
      in: query
      required: false
      schema:
        type: integer
      description: Page to display; valid values are integers >= 1
      example: 1
    Guid:
      name: guid
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: The unique identifier for the resource
  securitySchemes:
    oauth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://uaa.cloudfoundry.local/api-oauth/dialog
          scopes:
            cloud_controller.admin: This scope provides read and write access to all resources
            cloud_controller.admin_read_only: This scope provides read only access to all resources
            cloud_controller.global_auditor: This scope provides read access to all resources
            cloud_controller.read: Read access to the Cloud Controller
            cloud_controller.write: Write access to the Cloud Controller
            cloud_controller.update_build_state: This scope allows its bearer to update the state of a build; currently only used when updating builds
            cloud_controller_service_permissions.read: This scope provides read only access for service instance permissions
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer JWT token authentication