Platform.sh Http Traffic API

openapi: 3.2.0
info:
  title: Upsun.com Rest Http Traffic 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: Http Traffic
paths:
  /projects/{projectId}/environments/{environmentId}/observability/http/breakdown/urls:
    get:
      tags:
      - Http Traffic
      summary: Get HTTP traffic timeline by URL
      description: 'Returns HTTP traffic analytics with URLs ranked by impact (response time × request count), aggregated metrics (average, median, p96 response times in milliseconds), status code distributions, and time-series data. Use limit parameter to control total items returned (default: 200, max: 300) and top_hits_count to control how many items are flagged as top hits and tracked in the timeline (default: 10, max: 15). Items with index < top_hits_count are flagged with top_hit: true and tracked in top_hits_timeline; the remainder (up to limit) are returned with top_hit: false.'
      operationId: http_metrics_timeline_urls
      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: limit
        in: query
        description: 'Maximum number of items to return (default: 200, max: 300)'
        required: false
        schema:
          type: integer
          default: null
          maximum: 300
          minimum: 1
      - name: top_hits_count
        in: query
        description: 'Number of items to flag as top hits and track in the timeline (default: 10, max: 15). Items with index < top_hits_count have top_hit=true; the remainder up to limit are returned with top_hit=false.'
        required: false
        schema:
          type: integer
          default: null
          maximum: 15
          minimum: 1
      - name: applications[]
        in: query
        description: Filter by application. Can be specified multiple times for multiple values (e.g., ?applications[]=app1&applications[]=app2). Use applications_mode to control inclusion/exclusion behavior.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            example: app
      - 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: methods[]
        in: query
        description: Filter by HTTP methods. Can be specified multiple times for multiple values (e.g., ?methods[]=GET&methods[]=POST). Use methods_mode to control inclusion/exclusion behavior.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            example: GET
            enum:
            - GET
            - POST
            - PUT
            - PATCH
            - DELETE
            - HEAD
            - OPTIONS
      - name: methods_mode
        in: query
        description: 'Filter mode for methods parameter. "1" (additive) includes only specified methods. "-1" (subtractive) excludes specified methods and includes all others. When omitted: defaults to "-1" if no methods values are provided; defaults to "1" (additive) if at least one methods value is provided.'
        required: false
        schema:
          type: string
          example: '1'
          enum:
          - '1'
          - '-1'
      - name: domains[]
        in: query
        description: Filter by request domains/hosts. Can be specified multiple times for multiple values (e.g., ?domains[]=api.example.com&domains[]=www.example.com). Use domains_mode to control inclusion/exclusion behavior.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            example: api.example.com
      - name: domains_mode
        in: query
        description: 'Filter mode for domains parameter. "1" (additive) includes only specified domains. "-1" (subtractive) excludes specified domains and includes all others. When omitted: defaults to "-1" if no domains values are provided; defaults to "1" (additive) if at least one domains value is provided.'
        required: false
        schema:
          type: string
          example: '1'
          enum:
          - '1'
          - '-1'
      - name: code_slots[]
        in: query
        description: Filter by HTTP status code groups. Can be specified multiple times for multiple values (e.g., ?code_slots[]=4XX&code_slots[]=5XX). Use code_slots_mode to control inclusion/exclusion behavior.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            example: 2XX
            enum:
            - 1XX
            - 2XX
            - 3XX
            - 4XX
            - 5XX
      - name: code_slots_mode
        in: query
        description: 'Filter mode for code_slots parameter. "1" (additive) includes only specified code groups. "-1" (subtractive) excludes specified code groups and includes all others. When omitted: defaults to "-1" if no code_slots values are provided; defaults to "1" (additive) if at least one code_slots value is provided.'
        required: false
        schema:
          type: string
          example: '1'
          enum:
          - '1'
          - '-1'
      - name: codes[]
        in: query
        description: Filter by specific HTTP status codes. Can be specified multiple times for multiple values (e.g., ?codes[]=200&codes[]=404). Use codes_mode to control inclusion/exclusion behavior.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            example: '200'
      - name: codes_mode
        in: query
        description: 'Filter mode for codes parameter. "1" (additive) includes only specified codes. "-1" (subtractive) excludes specified codes and includes all others. When omitted: defaults to "-1" if no codes values are provided; defaults to "1" (additive) if at least one codes value is provided.'
        required: false
        schema:
          type: string
          example: '1'
          enum:
          - '1'
          - '-1'
      - name: request_duration_slots[]
        in: query
        description: Filter by response time ranges (in milliseconds). Can be specified multiple times for multiple values (e.g., ?request_duration_slots[]=0-50&request_duration_slots[]=1600+). Use request_duration_slots_mode to control inclusion/exclusion behavior.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            example: 0-50
            enum:
            - 0-50
            - 50-100
            - 100-200
            - 200-400
            - 400-800
            - 800-1600
            - 1600+
      - name: request_duration_slots_mode
        in: query
        description: 'Filter mode for request_duration_slots parameter. "1" (additive) includes only specified duration ranges. "-1" (subtractive) excludes specified duration ranges and includes all others. When omitted: defaults to "-1" if no request_duration_slots values are provided; defaults to "1" (additive) if at least one request_duration_slots value is provided.'
        required: false
        schema:
          type: string
          example: '1'
          enum:
          - '1'
          - '-1'
      responses:
        '200':
          description: HTTP traffic timeline by URL retrieved successfully
          content:
            application/json:
              schema:
                required:
                - _grain
                - _from
                - _to
                - _project_id
                - _environment_id
                - _environment_type
                - _branch_machine_name
                - _breakdown_limit
                - _breakdown_top_hits
                - breakdown
                - top_hits_timeline
                - filters
                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
                  _project_id:
                    description: Project identifier
                    type: string
                    example: abc123def456
                  _environment_id:
                    description: Environment identifier
                    type: string
                    example: main
                  _environment_type:
                    description: Environment type
                    type: string
                    example: production
                    enum:
                    - production
                    - staging
                    - development
                  _branch_machine_name:
                    description: Branch machine name
                    type: string
                    example: main-bvxea6i
                  _breakdown_limit:
                    description: Maximum number of items returned
                    type: integer
                    example: 200
                  _breakdown_top_hits:
                    description: Number of items flagged as top hits (top_hit=true) and tracked in top_hits_timeline.
                    type: integer
                    example: 10
                  _applications:
                    description: Applied application filter values
                    type:
                    - array
                    - 'null'
                    items:
                      type: string
                      example: app
                  _applications_mode:
                    description: Application filter mode (1=additive, -1=subtractive)
                    type:
                    - string
                    - 'null'
                    enum:
                    - '1'
                    - '-1'
                  _methods:
                    description: Applied method filter values
                    type:
                    - array
                    - 'null'
                    items:
                      type: string
                      example: GET
                  _methods_mode:
                    description: Method filter mode (1=additive, -1=subtractive)
                    type:
                    - string
                    - 'null'
                    enum:
                    - '1'
                    - '-1'
                  _domains:
                    description: Applied domain filter values
                    type:
                    - array
                    - 'null'
                    items:
                      type: string
                      example: example.com
                  _domains_mode:
                    description: Domain filter mode (1=additive, -1=subtractive)
                    type:
                    - string
                    - 'null'
                    enum:
                    - '1'
                    - '-1'
                  _code_slots:
                    description: Applied code slot filter values
                    type:
                    - array
                    - 'null'
                    items:
                      type: string
                      example: 2XX
                  _code_slots_mode:
                    description: Code slot filter mode (1=additive, -1=subtractive)
                    type:
                    - string
                    - 'null'
                    enum:
                    - '1'
                    - '-1'
                  _codes:
                    description: Applied HTTP status code filter values
                    type:
                    - array
                    - 'null'
                    items:
                      type: string
                      example: '200'
                  _codes_mode:
                    description: Code filter mode (1=additive, -1=subtractive)
                    type:
                    - string
                    - 'null'
                    enum:
                    - '1'
                    - '-1'
                  _request_duration_slots:
                    description: Applied request duration slot filter values
                    type:
                    - array
                    - 'null'
                    items:
                      type: string
                      example: 0-100
                  _request_duration_slots_mode:
                    description: Request duration slot filter mode (1=additive, -1=subtractive)
                    type:
                    - string
                    - 'null'
                    enum:
                    - '1'
                    - '-1'
                  breakdown:
                    description: URLs ranked by impact
                    required:
                    - kind
                    - total
                    - data
                    properties:
                      kind:
                        description: The kind of grouping
                        type: string
                        example: url
                        enum:
                        - url
                      total:
                        description: Total request count across all URLs
                        type: integer
                        example: 396519
                      data:
                        description: 'List of URLs ranked by impact. Items with index < top_hits_count are tracked in top_hits_timeline (flagged with top_hit: true); the remainder are returned for reference only.'
                        type: array
                        items:
                          required:
                          - url
                          - method
                          - impact
                          - average
                          - p_50
                          - p_96
                          - count
                          - top_hit
                          properties:
                            url:
                              description: Request URL
                              type: string
                              example: https://example.com/api/products
                            method:
                              description: HTTP method
                              type: string
                              example: GET
                              enum:
                              - GET
                              - POST
                              - PUT
                              - PATCH
                              - DELETE
                              - HEAD
                              - OPTIONS
                            impact:
                              description: Performance impact score (ms x count)
                              type:
                              - number
                              - 'null'
                              format: float
                              example: 15234.67
                            average:
                              description: Average response time in milliseconds
                              type: number
                              format: float
                              example: 245.3
                            p_50:
                              description: Median (50th percentile) response time in milliseconds
                              type: number
                              format: float
                              example: 198.5
                            p_96:
                              description: 96th percentile response time in milliseconds
                              type: number
                              format: float
                              example: 512.8
                            count:
                              description: Total number of requests
                              type: integer
                              example: 62143
                            top_hit:
                              description: Whether this URL is tracked in top_hits_timeline
                              type: boolean
                              example: true
                          type: object
                          additionalProperties: false
                        example:
                        - url: https://example.com/api/products
                          method: GET
                          impact: 15234.67
                          average: 245.3
                          p_50: 198.5
                          p_96: 512.8
                          count: 62143
                          top_hit: true
                        - url: https://example.com/api/orders
                          method: POST
                          impact: 6543.21
                          average: 312.5
                          p_50: 267.8
                          p_96: 678.4
                          count: 20945
                          top_hit: false
                    type: object
                    additionalProperties: false
                  top_hits_timeline:
                    description: Time-series data for top hit URLs
                    required:
                    - data
                    properties:
                      data:
                        description: Time-series HTTP traffic metrics for top hit URLs. Fields are omitted for timestamps with no data.
                        type: array
                        items:
                          required:
                          - timestamp
                          properties:
                            timestamp:
                              description: Data point timestamp
                              type: integer
                              example: 1704067200
                            _total_consumed:
                              description: Total wall-time consumed across all URLs at this interval
                              type: number
                              format: float
                              example: 5678.9
                            _total_count:
                              description: Total request count at this timestamp
                              type: integer
                              example: 4120
                            request_size:
                              description: Total request payload size in bytes
                              type: integer
                              example: 524288
                            response_size:
                              description: Total response payload size in bytes
                              type: integer
                              example: 2097152
                            urls:
                              description: Per-URL metrics at this timestamp. Only includes top hit items.
                              type: object
                              example:
                                GET-https://example.com/api/products:
                                  count: 1543
                                  impact: 378.45
                              additionalProperties:
                                required:
                                - count
                                - impact
                                properties:
                                  count:
                                    description: Request count for this URL
                                    type: integer
                                    example: 1543
                                  impact:
                                    description: Performance impact score
                                    type:
                                    - number
                                    - 'null'
                                    format: float
                                    example: 378.45
                                type: object
                                additionalProperties: false
                            codes:
                              description: HTTP status code distribution
                              required:
                              - UNKNOWN
                              - 1XX
                              - 2XX
                              - 3XX
                              - 4XX
                              - 5XX
                              properties:
                                UNKNOWN:
                                  description: Count of unknown/unclassified status codes
                                  type: integer
                                  example: 0
                                1XX:
                                  description: Count of informational responses (100-199)
                                  type: integer
                                  example: 0
                                2XX:
                                  description: Count of successful responses (200-299)
                                  type: integer
                                  example: 58234
                                3XX:
                                  description: Count of redirect responses (300-399)
                                  type: integer
                                  example: 1245
                                4XX:
                                  description: Count of client error responses (400-499)
                                  type: integer
                                  example: 847
                                5XX:
                                  description: Count of server error responses (500-599)
                                  type: integer
                                  example: 23
                              type: object
                              additionalProperties: false
                          type: object
                          additionalProperties: false
                        example:
                        - timestamp: 1704067200
                          _total_consumed: 5678.9
                          _total_count: 1543
                          request_size: 524288
                          response_size: 2097152
                          urls:
                            GET-https://example.com/api/products:
                              count: 1543
                              impact: 378.45
                          codes:
                            UNKNOWN: 0
                            1XX: 0
                            2XX: 1543
                            3XX: 0
                            4XX: 0
                            5XX: 0
                        - timestamp: 1704070800
                    type: object
                    additionalProperties: false
                  filters:
                    required:
                    - max_applicable_filters
                    properties:
                      fields:
                        type: object
                        example:
                          severity:
                            distinct_values: 3
                            type: string
                            values:
                            - value: INFO
                              count: 297
                            - value: ERROR
                              count: 2
                        additionalProperties:
                          required:
                          - distinct_values
                          - type
                          - values
                          properties:
                            distinct_values:
                              type: integer
                              example: 5
                            type:
                              type: string
                              example: string
                            values:
                              type: array
                              items:
                                required:
                                - value
                                - count
                                properties:
                                  value:
                                    type: string
                                    example: I

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