Platform.sh Blackfire Monitoring API

openapi: 3.2.0
info:
  title: Upsun.com Rest Blackfire Monitoring API
  version: '1.0'
  contact:
    name: Support
    url: https://upsun.com/contact-us/
  termsOfService: https://upsun.com/trust-center/legal/tos/
  description: "# Introduction\n\nUpsun, formerly Platform.sh, is a container-based Platform-as-a-Service. Our main API\nis simply Git. With a single `git push` and a couple of YAML files in\nyour repository you can deploy an arbitrarily complex cluster.\nEvery [**Project**](#tag/Project) can have multiple applications (PHP,\nNode.js, Python, Ruby, Go, etc.) and managed, automatically\nprovisioned services (databases, message queues, etc.).\n\nEach project also comes with multiple concurrent\nlive staging/development [**Environments**](#tag/Environment).\nThese ephemeral development environments\nare automatically created every time you push a new branch or create a\npull request, and each has a full copy of the data of its parent branch,\nwhich is created on-the-fly in seconds.\n\nOur Git implementation supports integrations with third party Git\nproviders such as GitHub, Bitbucket, or GitLab, allowing you to simply\nintegrate Upsun into your existing workflow.\n\n## Using the REST API\n\nIn addition to the Git API, we also offer a REST API that allows you to manage\nevery aspect of the platform, from managing projects and environments,\nto accessing accounts and subscriptions, to creating robust workflows\nand integrations with your CI systems and internal services.\n\nThese API docs are generated from a standard **OpenAPI (Swagger)** Specification document\nwhich you can find here in [YAML](openapispec-upsun.yaml) and in [JSON](openapispec-upsun.json) formats.\n\nThis RESTful API consumes and produces HAL-style JSON over HTTPS,\nand any REST library can be used to access it. On GitHub, we also host\na few API libraries that you can use to make API access easier, such as our\n[PHP API client](https://github.com/upsun/upsun-sdk-php).\n\nIn order to use the API you will first need to have an [Upsun account](https://auth.upsun.com/register/)\nand [create an API Token](https://docs.upsun.com/anchors/cli/api-token/).\n\n# Authentication\n\n## OAuth2\n\nAPI authentication is done with OAuth2 access tokens.\n\n### API tokens\n\nYou can use an API token as one way to get an OAuth2 access token. This\nis particularly useful in scripts, e.g. for CI pipelines.\n\nTo create an API token, go to the \"API Tokens\" section\nof the \"Account Settings\" tab on the [Console](https://console.upsun.com).\n\nTo exchange this API token for an access token, a `POST` request\nmust be made to `https://auth.upsun.com/oauth2/token`.\n\nThe request will look like this in cURL:\n\n<pre>\ncurl -u platform-api-user: \\\n    -d 'grant_type=api_token&amp;api_token=<em><b>API_TOKEN</b></em>' \\\n    https://auth.upsun.com/oauth2/token\n</pre>\n\nThis will return a \"Bearer\" access token that\ncan be used to authenticate further API requests, for example:\n\n<pre>\n{\n    \"access_token\": \"<em><b>abcdefghij1234567890</b></em>\",\n    \"expires_in\": 900,\n    \"token_type\": \"bearer\"\n}\n</pre>\n\n### Using the Access Token\n\nTo authenticate further API requests, include this returned bearer token\nin the `Authorization` header. For example, to retrieve a list of\n[Projects](#tag/Project)\naccessible by the current user, you can make the following request\n(substituting the dummy token for your own):\n\n<pre>\ncurl -H \"Authorization: Bearer <em><b>abcdefghij1234567890</b></em>\" \\\n    https://api.upsun.com/projects\n</pre>\n\n# HAL Links\n\nMost endpoints in the API return fields which defines a HAL\n(Hypertext Application Language) schema for the requested endpoint.\nThe particular objects returns and their contents can vary by endpoint.\nThe payload examples we give here for the requests do not show these\nelements. These links can allow you to create a fully dynamic API client\nthat does not need to hardcode any method or schema.\n\nUnless they are used for pagination we do not show the HAL links in the\npayload examples in this documentation for brevity and as their content\nis contextual (based on the permissions of the user).\n\n## _links Objects\n\nMost endpoints that respond to `GET` requests will include a `_links` object\nin their response. The `_links` object contains a key-object pair labelled `self`, which defines\ntwo further key-value pairs:\n\n* `href` - A URL string referring to the fully qualified name of the returned object. For many endpoints, this will be the direct link to the API endpoint on the region gateway, rather than on the general API gateway. This means it may reference a host of, for example, `eu-2.platform.sh` rather than `api.upsun.com`.\n* `meta` - An object defining the OpenAPI Specification (OAS) [schema object](https://swagger.io/specification/#schemaObject) of the component returned by the endpoint.\n\nThere may be zero or more other fields in the `_links` object resembling fragment identifiers\nbeginning with a hash mark, e.g. `#edit` or `#delete`. Each of these keys\nrefers to a JSON object containing two key-value pairs:\n\n* `href` - A URL string referring to the path name of endpoint which can perform the action named in the key.\n* `meta` - An object defining the OAS schema of the endpoint. This consists of a key-value pair, with the key defining an HTTP method and the value defining the [operation object](https://swagger.io/specification/#operationObject) of the endpoint.\n\nTo use one of these HAL links, you must send a new request to the URL defined\nin the `href` field which contains a body defined the schema object in the `meta` field.\n\nFor example, if you make a request such as `GET /projects/abcdefghij1234567890`, the `_links`\nobject in the returned response will include the key `#delete`. That object\nwill look something like this fragment:\n\n```\n\"#delete\": {\n    \"href\": \"/api/projects/abcdefghij1234567890\",\n    \"meta\": {\n        \"delete\": {\n            \"responses\": {\n                . . . // Response definition omitted for space\n            },\n            \"parameters\": []\n        }\n    }\n}\n```\n\nTo use this information to delete a project, you would then send a `DELETE`\nrequest to the endpoint `https://api.upsun.com/api/projects/abcdefghij1234567890`\nwith no body or parameters to delete the project that was originally requested.\n\n## _embedded Objects\n\nRequests to endpoints which create or modify objects, such as `POST`, `PATCH`, or `DELETE`\nrequests, will include an `_embedded` key in their response. The object\nrepresented by this key will contain the created or modified object. This\nobject is identical to what would be returned by a subsequent `GET` request\nfor the object referred to by the endpoint.\n"
  x-logo:
    url: https://docs.upsun.com/images/upsun-api.svg
    href: https://upsun.com/#section/Introduction
    altText: Upsun logo
servers:
- url: '{schemes}://api.upsun.com'
  description: The Upsun.com API gateway
  variables:
    schemes:
      default: https
security:
- BearerAuth: []
tags:
- name: Blackfire Monitoring
paths:
  /projects/{projectId}/environments/{environmentId}/observability/server/caches:
    get:
      tags:
      - Blackfire Monitoring
      summary: Get server cache metrics
      description: Returns time-series PHP cache usage ratios (0.0-1.0) for OPcache memory, OPcache interned strings buffer (ISB), APCu memory, realpath cache, and PCRE cache. Includes hit rate ratios (0.0-1.0) for APCu and OPcache. Each data point contains `timestamp` and optional data fields. Fields are omitted for timestamps with no data - this indicates no data was received. Filtered by agent ID and execution contexts (web, cli, etc.).
      operationId: blackfire_php_server_caches
      parameters:
      - name: projectId
        in: path
        description: The unique identifier of the Upsun project
        required: true
        schema:
          type: string
          pattern: '[a-z0-9]+'
          example: abc123def456
      - name: environmentId
        in: path
        description: The environment identifier
        required: true
        schema:
          type: string
          pattern: .+
          example: main
      - name: from
        in: query
        description: Start timestamp for the time range (Unix timestamp in seconds)
        required: true
        schema:
          type: integer
          format: int64
          example: 1704067200
      - name: to
        in: query
        description: End timestamp for the time range (Unix timestamp in seconds)
        required: true
        schema:
          type: integer
          format: int64
          example: 1704153600
      - name: grain
        in: query
        description: Granularity of data points in seconds. Auto-calculated if omitted.
        required: false
        schema:
          type: integer
          example: 10
      - name: contexts[]
        in: query
        description: Filter by execution contexts. Defaults to ["web"] with additive mode when neither contexts nor contexts_mode is specified.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            example: web
            enum:
            - web
            - cli
      - name: contexts_mode
        in: query
        description: Filter mode for contexts parameter. "1" (additive, default) includes only specified contexts. "-1" (subtractive) excludes specified contexts and includes all others. When neither contexts nor contexts_mode is specified, defaults to "1" (additive) with contexts=["web"].
        required: false
        schema:
          type: string
          example: '1'
          default: null
          enum:
          - '1'
          - '-1'
      - name: applications[]
        in: query
        description: Filter by application names
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            example: app-frontend
      - name: applications_mode
        in: query
        description: 'Filter mode for applications parameter. "1" (additive) includes only specified applications. "-1" (subtractive) excludes specified applications and includes all others. When omitted: defaults to "-1" if no applications values are provided; defaults to "1" (additive) if at least one applications value is provided.'
        required: false
        schema:
          type: string
          example: '1'
          enum:
          - '1'
          - '-1'
      - name: instances[]
        in: query
        description: Filter by instance names
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            example: app-frontend.0
      - name: instances_mode
        in: query
        description: 'Filter mode for instances parameter. "1" (additive) includes only specified instances. "-1" (subtractive) excludes specified instances and includes all others. When omitted: defaults to "-1" if no instances values are provided; defaults to "1" (additive) if at least one instances value is provided.'
        required: false
        schema:
          type: string
          example: '1'
          enum:
          - '1'
          - '-1'
      - name: distribution_cost
        in: query
        description: Cost distribution dimension for server load distribution.
        required: false
        schema:
          type: string
          default: null
          enum:
          - wt
          - pmu
      responses:
        '200':
          description: PHP server cache metrics retrieved successfully
          content:
            application/json:
              schema:
                required:
                - _grain
                - _from
                - _to
                - _agent
                - _distribution_cost
                - _project_id
                - _environment_id
                - _branch_machine_name
                - data
                properties:
                  _grain:
                    description: Data granularity in seconds
                    type: integer
                    example: 5
                  _from:
                    description: Query start timestamp
                    type: integer
                    example: 1704067200
                  _to:
                    description: Query end timestamp
                    type: integer
                    example: 1704153600
                  _agent:
                    description: Blackfire Agent UUID
                    type: string
                    format: uuid
                    example: a38f69ca-3b56-4ea6-beac-272b2568164a
                  _project_id:
                    description: Project identifier
                    type: string
                    example: abc123def456
                  _environment_id:
                    description: Environment identifier
                    type: string
                    example: main
                  _branch_machine_name:
                    description: Branch machine name
                    type: string
                    example: main-bvxea6i
                  _contexts:
                    description: Applied context filter values
                    type:
                    - array
                    - 'null'
                    items:
                      type: string
                      example: web
                  _contexts_mode:
                    description: Context filter mode (additive=include only, subtractive=exclude)
                    type:
                    - string
                    - 'null'
                    enum:
                    - additive
                    - subtractive
                  _applications:
                    description: Applied application filter values
                    type:
                    - array
                    - 'null'
                    items:
                      type: string
                      example: app-frontend
                  _applications_mode:
                    description: Application filter mode (additive=include only, subtractive=exclude)
                    type:
                    - string
                    - 'null'
                    enum:
                    - additive
                    - subtractive
                  _instances:
                    description: Applied instance filter values
                    type:
                    - array
                    - 'null'
                    items:
                      type: string
                      example: app-frontend.0
                  _instances_mode:
                    description: Instance filter mode (additive=include only, subtractive=exclude)
                    type:
                    - string
                    - 'null'
                    enum:
                    - additive
                    - subtractive
                  _distribution_cost:
                    description: Applied distribution cost dimension (wt=wall time, pmu=peak memory usage)
                    type: string
                    enum:
                    - wt
                    - pmu
                  data:
                    description: Time-series cache usage metrics. Each data point contains `timestamp` and optional data fields. Fields are omitted for timestamps with no data - this indicates no data was received.
                    type: array
                    items:
                      required:
                      - timestamp
                      properties:
                        timestamp:
                          description: Data point timestamp (Unix timestamp in seconds)
                          type: integer
                          example: 1764083014
                        opcache_usage:
                          description: OPcache memory usage ratio (0.0-1.0, where 1.0 = 100% full)
                          type:
                          - number
                          - 'null'
                          format: float
                          example: 0.308
                        opcache_isb_usage:
                          description: OPcache interned strings buffer usage ratio (0.0-1.0)
                          type:
                          - number
                          - 'null'
                          format: float
                          example: 0.629
                        apcu_usage:
                          description: APCu memory usage ratio (0.0-1.0)
                          type:
                          - number
                          - 'null'
                          format: float
                          example: 0.008
                        realpath_usage:
                          description: Realpath cache usage ratio (0.0-1.0)
                          type:
                          - number
                          - 'null'
                          format: float
                          example: 0.109
                        pcre_usage:
                          description: PCRE (Perl Compatible Regular Expressions) cache usage ratio (0.0-1.0)
                          type:
                          - number
                          - 'null'
                          format: float
                          example: 0.304
                        apcu_hitrate:
                          description: APCu cache hit rate ratio (0.0-1.0, where 1.0 = 100% hits)
                          type:
                          - number
                          - 'null'
                          format: float
                          example: 0.999
                        opcache_hitrate:
                          description: OPcache hit rate ratio (0.0-1.0, where 1.0 = 100% hits)
                          type:
                          - number
                          - 'null'
                          format: float
                          example: 0.9998
                      type: object
                      additionalProperties: false
                type: object
                additionalProperties: false
              example:
                _grain: 2
                _from: 1764083002
                _to: 1764083092
                _agent: 4b5266a2-fd71-468b-bf05-87b342079cbf
                _project_id: abc123def456
                _environment_id: main
                _branch_machine_name: main-bvxea6i
                _contexts:
                - web
                _contexts_mode: additive
                _distribution_cost: wt
                data:
                - timestamp: 1764083002
                - timestamp: 1764083014
                  opcache_usage: 0.308
                  opcache_isb_usage: 0.629
                  apcu_usage: 0.008
                  realpath_usage: 0.109
                  pcre_usage: 0.304
                  apcu_hitrate: 0.999
                  opcache_hitrate: 0.9998
                - timestamp: 1764083024
                  opcache_usage: 0.308
                  opcache_isb_usage: 0.629
                  apcu_usage: 0.008
                  realpath_usage: 0.105
                  pcre_usage: 0.313
                  apcu_hitrate: 0.999
                  opcache_hitrate: 0.9998
        '400':
          description: Bad request - Invalid parameters. Please consult the API documentation to fix the request parameters.
          content:
            application/json:
              schema:
                required:
                - type
                - title
                - status
                - violations
                properties:
                  type:
                    description: RFC 2616 reference URL identifying the error type
                    type: string
                    format: uri
                    example: https://tools.ietf.org/html/rfc2616#section-1
                  title:
                    description: Human-readable summary of the validation error
                    type: string
                    example: Please ensure parameters are correct.
                  status:
                    description: HTTP status code
                    type: integer
                    example: 400
                  violations:
                    description: Map of parameter names to their validation errors. Each parameter can have multiple error messages.
                    type: object
                    example:
                      grain:
                      - Grain can not be larger than the selection windows.
                      from:
                      - The from timestamp must be in the past.
                      to:
                      - The to timestamp must be greater than the from timestamp.
                    additionalProperties:
                      type: array
                      items:
                        type: string
                        example: The from timestamp must be in the past.
                type: object
                additionalProperties: false
        '403':
          description: Forbidden - Access denied due to insufficient permissions, or the requested project/environment does not exist (to prevent information disclosure)
        '499':
          description: Too much data fetched - The query is attempting to retrieve too much data. Please narrow down the query by reducing the time range or adding more specific filters to retrieve less data.
          content:
            application/json:
              schema:
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    example: Too much data fetched
                  message:
                    type: string
                    example: Please reduce the time range or add more filters to narrow down the query
                type: object
                additionalProperties: false
  /projects/{projectId}/environments/{environmentId}/observability/server:
    get:
      tags:
      - Blackfire Monitoring
      summary: Get server monitoring overview
      description: Returns time-series server monitoring data for the specified metrics (wall time, memory usage, peak memory usage, CPU load, stdout, requests per minute). Includes alert evaluations and APM quota usage. Data points contain metric values aggregated at the requested granularity.
      operationId: blackfire_server_global
      parameters:
      - name: projectId
        in: path
        description: The unique identifier of the Upsun project
        required: true
        schema:
          type: string
          pattern: '[a-z0-9]+'
          example: abc123def456
      - name: environmentId
        in: path
        description: The environment identifier
        required: true
        schema:
          type: string
          pattern: .+
          example: main
      - name: from
        in: query
        description: Start timestamp for the time range (Unix timestamp in seconds)
        required: true
        schema:
          type: integer
          format: int64
          example: 1704067200
      - name: to
        in: query
        description: End timestamp for the time range (Unix timestamp in seconds)
        required: true
        schema:
          type: integer
          format: int64
          example: 1704153600
      - name: keys[]
        in: query
        description: Metrics to retrieve (wall time, memory usage, peak memory, CPU load, stdout, requests per minute)
        required: true
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - wt
            - mu
            - pmu
            - load
            - stdout
            - rpms
      - name: grain
        in: query
        description: Granularity of data points in seconds. Auto-calculated if omitted.
        required: false
        schema:
          type: integer
          example: 10
      - name: contexts[]
        in: query
        description: Filter by execution contexts. Defaults to ["web"] with additive mode when neither contexts nor contexts_mode is specified.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            example: web
            enum:
            - web
            - cli
      - name: contexts_mode
        in: query
        description: Filter mode for contexts parameter. "1" (additive, default) includes only specified contexts. "-1" (subtractive) excludes specified contexts and includes all others. When neither contexts nor contexts_mode is specified, defaults to "1" (additive) with contexts=["web"].
        required: false
        schema:
          type: string
          example: '1'
          default: null
          enum:
          - '1'
          - '-1'
      - name: applications[]
        in: query
        description: Filter by application names
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            example: app-frontend
      - name: applications_mode
        in: query
        description: 'Filter mode for applications parameter. "1" (additive) includes only specified applications. "-1" (subtractive) excludes specified applications and includes all others. When omitted: defaults to "-1" if no applications values are provided; defaults to "1" (additive) if at least one applications value is provided.'
        required: false
        schema:
          type: string
          example: '1'
          enum:
          - '1'
          - '-1'
      - name: instances[]
        in: query
        description: Filter by instance names
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            example: app-frontend.0
      - name: instances_mode
        in: query
        description: 'Filter mode for instances parameter. "1" (additive) includes only specified instances. "-1" (subtractive) excludes specified instances and includes all others. When omitted: defaults to "-1" if no instances values are provided; defaults to "1" (additive) if at least one instances value is provided.'
        required: false
        schema:
          type: string
          example: '1'
          enum:
          - '1'
          - '-1'
      - name: distribution_cost
        in: query
        description: Cost distribution dimension for server load distribution.
        required: false
        schema:
          type: string
          default: null
          enum:
          - wt
          - pmu
      responses:
        '200':
          description: Server global metrics retrieved successfully
          content:
            application/json:
              schema:
                required:
                - _quota
                - _grain
                - _from
                - _to
                - _keys
                - _agent
                - _contexts
                - _contexts_mode
                - _project_id
                - _environment_id
                - _branch_machine_name
                - alert_evaluations
                - server
                properties:
                  _quota:
                    description: APM quota usage information
                    required:
                    - allowed
                    - used
                    - exceeded
                    - period_started_at
                    - period_ends_at
                    properties:
                      allowed:
                        description: APM quota limit
                        type: integer
                        example: 2147000000
                      used:
                        description: Traces used in current period
                        type: integer
                        example: 103139
                      exceeded:
                        description: Whether quota is exceeded
                        type: boolean
                        example: false
                      period_started_at:
                        description: Billing period start
                        type:
                        - string
                        - 'null'
                        format: date-time
                        example: '2026-02-01T00:00:00+00:00'
                      period_ends_at:
                        description: Billing period end
                        type:
                        - string
                        - 'null'
                        format: date-time
                        example: '2026-03-01T00:00:00+00:00'
                    type: object
                    additionalProperties: false
                  _grain:
                    description: Data granularity in seconds
                    type: integer
                    example: 5
                  _from:
                    description: Query start timestamp
                    type: integer
                    example: 1704067200
                  _to:
                    description: Query end timestamp
                    type: integer
                    example: 1704153600
                  _keys:
                    description: Requested metric keys
                    type: array
                    items:
                      type: string
                      example: wt
                    example:
                    - wt
                    - rpms
                  _agent:
                    description: Blackfire Agent UUID
                    type: string
                    format: uuid
                    example: a38f69ca-3b56-4ea6-beac-272b2568164a
                  _contexts:
                    description: Applied context filter values
                    type:
                    - array
                    - 'null'
                    items:
                      type: string
                      example: web
                  _contexts_mode:
                    description: Context filter mode (additive=include only, subtractive=exclude)
                    type:
                    - string
                    - 'null'
                    enum:
                    - additive
                    - subtractive
                  _applications:
                    description: Applied application filter values
                    type:
                    - array
                    - 'null'
                    items:
                      type: string
                      example: app-frontend
                  _applications_mode:
                    description: Application filter mode (additive=include only, subtractive=exclude)
                    type:
                    - string
                    - 'null'
                    enum:
                    - additive
                    - subtractive
                  _instances:
                    description: Applied instance filter values
                    type:
                    - array
                    - 'null'
                    items:
                      type: string
                      example: app-frontend.0
                  _instances_mode:
                    description: Instance filter mode (additive=include only, subtractive=exclude)
                    type:
                    - string
                    - 'null'
                    enum:
                    - additive
                    - subtractive
                  _distribution_cost:
                    description: Applied distribution cost dimension (wt=wall time, pmu=peak memory usage)
                    type: string
                    enum:
                    - wt
                    - pmu
                  _project_id:
                    description: Project identifier
                    type: string
                    example: abc123def456
                  _environment_id:
                    description: Environment identifier
                    type: string
                    example: main
                  _branch_machine_name:
                    description: Branch machine name
                    type: string
                    example: main-bvxea6i
                  alert_evaluations:
                    description: Alert rule evaluations for the time range
                    type: array
                    items:
                      required:
              

# --- truncated at 32 KB (117 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/platform.sh/refs/heads/main/openapi/platform.sh-blackfire-monitoring-api-openapi.yml