API reference

API Authentication and Settings Management for Judoscale Users

Getting Started

Authentication

All requests to the API should use ENV['JUDOSCALE_URL'] as the base URL. This environment variable is created by Judoscale and Heroku when you install the add-on, and it may change without notice. For non-Heroku integrations, JUDOSCALE_URL is provided when setting up your service or cluster.

The URL includes a unique token which is used to authenticate your request.

Content Type

The API expects payloads using JSON format to process POST/PUT/PATCH requests appropriately. Make sure to set the Content-Type: application/json header when sending those requests.

Settings

This endpoint returns a snapshot of your current app settings.

GET /settings

Example:

GET /settings

Optional query params:

  • backward_compatible_attributes=false
    • Excludes legacy attributes such as the top-level upscale_threshold and downscale_threshold keys that we continue to expose for older API integrations. Use this flag when you plan to pipe the response directly into PATCH /process_type, such as when migrating settings between platforms or teams. The payload produced with this flag contains only the modern autoscale_metrics collection, which aligns with what the PATCH endpoint expects.

Returns (JSON):

{
  "slack_webhook_url": "",
  "name": "example",
  "process_types": [
    {
      "name": "web",
      "autoscaling_enabled": true,
      "range_min": 2,
      "range_max": 12,
      "upscale_threshold": 100,
      "upscale_quantity": 2,
      "upscale_interval_seconds": 120,
      "upscale_sensitivity_seconds": 10,
      "downscale_threshold": 50,
      "downscale_quantity": 1,
      "downscale_interval_seconds": 600,
      "autoscale_metrics": [
        {
          "metric": "adapter_queue_time",
          "upscale_threshold": 100,
          "downscale_threshold": 50
        }
      ]
    },
    {
      "name": "worker",
      "autoscaling_enabled": true,
      "all_queues": false,
      "queue_names": ["default", "high"],
      "range_min": 1,
      "range_max": 6,
      "upscale_threshold": 10000,
      "upscale_quantity": 2,
      "upscale_interval_seconds": 120,
      "upscale_sensitivity_seconds": 10,
      "downscale_threshold": 1000,
      "downscale_quantity": 1,
      "downscale_interval_seconds": 600,
      "autoscale_metrics": [
        {
          "metric": "adapter_queue_time",
          "upscale_threshold": 10000,
          "downscale_threshold": 1000
        }
      ]
    }
  ]
}

πŸ‘€ Note

Judoscale now supports autoscaling on multiple metrics. The settings API will always include the autoscale_metrics array, containing the enabled metrics and associated upscale and downscale thresholds. When a single metric is used for autoscaling (the default as shown in the example above), we’ll also inline the upscale_threshold and downscale_threshold values with the process type attributes for backward compatibility with the API prior to the introduction of multiple autoscaling metrics. However, when multiple metrics are configured, those thresholds will not be included with the process type, only within their respective autoscale_metrics. Below is an example for the web process with multiple autoscale metrics:

{
  "process_types": [
    {
      "name": "web",
      "autoscaling_enabled": true,
      "range_min": 2,
      "range_max": 12,
      "upscale_quantity": 2,
      "upscale_interval_seconds": 120,
      "upscale_sensitivity_seconds": 10,
      "downscale_quantity": 1,
      "downscale_interval_seconds": 600,
      "autoscale_metrics": [
        {
          "metric": "adapter_queue_time",
          "upscale_threshold": 100,
          "downscale_threshold": 50
        },
        {
          "metric": "adapter_utilization",
          "upscale_threshold": 60,
          "downscale_threshold": 40
        }
      ]
    }
  ]
}

New implementations are recommended to read the thresholds from autoscale_metrics, regardless of using single or multiple metrics for autoscaling.

The possible metric values are:

  • For web processes:
  • For worker processes:
    • adapter_queue_time: autoscaling using queue time
    • adapter_queue_depth: autoscaling using queue depth/size (only available on some adapter packages)
    • scaling_schedule: autoscaling using a schedule

Process Types

Judoscale settings are organized by Process Type.

  • For Heroku, each Process Type corresponds to a line in your Procfile, such as “web”, “worker”, etc.
  • For Render, Railway, & Amazon ECS, each Process Type corresponds to a service.
  • For Fly.io, each Process Type corresponds to a Fly “process group”

GET /process_type/:name

Example:

GET /process_type/web

Returns (JSON):

{
  "process_type": {
    "name": "web",
    "autoscaling_enabled": true,
    "range_min": 2,
    "range_max": 12,
    "upscale_quantity": 2,
    "upscale_interval_seconds": 120,
    "upscale_sensitivity_seconds": 10,
    "downscale_quantity": 1,
    "downscale_interval_seconds": 600,
    "autoscale_metrics": [
      {
        "metric": "adapter_queue_time",
        "upscale_threshold": 100,
        "downscale_threshold": 50
      }
    ]
  }
}

worker processes have a couple additional settings for controlling the queues to monitor:

{
  "process_type": {
    "name": "worker",
    "all_queues": false,
    "queue_names": ["default", "high"]
  }
}

PATCH /process_type

Use this endpoint to update autoscaling settings for a process type. name is required.

πŸ‘€ Note

Process types are created by Judoscale when we sync with your platform. The PATCH endpoint updates an existing process typeβ€”it will not create a new one. When you pass an autoscale_metrics payload, the API will create any metrics that do not yet exist on the process type and update those that do.

This example would enable autoscaling, set the upscale threshold to 100ms, the downscale threshold to 50ms, and the autoscale range as 2–10 dynos:

PATCH /process_type

Request body (JSON):

{
  "process_type": {
    "name": "web",
    "autoscaling_enabled": true,
    "range_min": 2,
    "range_max": 10,
    "upscale_threshold": 100,
    "downscale_threshold": 50
  }
}

All the available settings for web and worker processes are shown below:

{
  "process_type": {
    "name": "web",
    "autoscaling_enabled": true,
    "range_min": 2,
    "range_max": 12,
    "upscale_threshold": 100,
    "upscale_quantity": 2,
    "upscale_interval_seconds": 120,
    "upscale_sensitivity_seconds": 10,
    "downscale_threshold": 50,
    "downscale_quantity": 1,
    "downscale_interval_seconds": 600,
    "autoscale_metrics": [
      {
        "metric": "adapter_queue_time",
        "upscale_threshold": 100,
        "downscale_threshold": 50
      }
    ]
  }
}

worker processes have a couple additional settings for controlling the queues to monitor:

{
  "process_type": {
    "name": "worker",
    "all_queues": false,
    "queue_names": ["default", "high"]
  }
}

The response is the same as GET /process_type/:name.

πŸ‘€ Note

As noted previously, Judoscale now supports autoscaling on multiple metrics. Our PATCH /process_type API supports updating the upscale_threshold and downscale_threshold as part of the process type payload for backward compatibility, but this is only possible if the process type is using a single metric for autoscaling. When multiple metrics are enabled, that update will be blocked and autoscale_metrics must be passed instead, as shown below:

{
  "process_type": {
    "name": "web",
    "autoscale_metrics": [
      {
        "metric": "adapter_queue_time",
        "upscale_threshold": 100,
        "downscale_threshold": 50
      },
      {
        "metric": "adapter_utilization",
        "upscale_threshold": 60,
        "downscale_threshold": 40
      }
    ]
  }
}

New implementations are recommended to update the thresholds using autoscale_metrics, regardless of using single or multiple metrics for autoscaling.

Scale Range Settings (schedules)

Autoscaling schedules can be fetched and updated via the scale_range_settings endpoints.

GET /process_type/:name/scale_range_settings

Example:

GET /process_type/web/scale_range_settings

Returns (JSON):

{
  "scale_range_settings": [
    {
      "wday": 2,
      "time": "16:30",
      "range_min": 2,
      "range_max": 4
    },
    {
      "wday": 3,
      "time": "00:00",
      "range_min": 3,
      "range_max": 5
    }
  ]
}

PATCH /process_type/:name/scale_range_settings

Use this endpoint to replace all scale range settings for a process.

Example:

PATCH /process_type/worker/scale_range_settings

Request body (JSON):

{
  "scale_range_settings": [
    {
      "wday": 2,
      "time": "16:30",
      "range_min": 2,
      "range_max": 99
    },
    {
      "wday": 3,
      "time": "00:00",
      "range_min": 3,
      "range_max": 5
    }
  ]
}

Validation errors return a 422 status code and look like this:

{
  "errors": [["exceeds the plan limit"], []]
}

Maintenance Mode

Maintenance mode allows you to pause autoscaling for an entire app, and resume it again when ready, without having to disable autoscaling for each process.

See maintenance mode for more information.

POST /maintenance

Enables maintenance mode, which pauses autoscaling, and scales the app’s worker processes with autoscaling enabled down to zero.

POST /maintenance

Returns (JSON):

{
  "name": "example",
  "maintenance_enabled_at": "2024-01-01T01:01:01.000Z"
}

In case there’s any error from the platform trying to scale the processes down, maintenance mode will still be enabled, and we’ll return an additional errors key:

{
  "name": "example",
  "maintenance_enabled_at": "2024-01-01T01:01:01.000Z",
  "errors": ["error setting new scales: {\"worker\"=>0}"]
}

DELETE /maintenance

Disables maintenance mode, which resumes autoscaling, and attempts to scale the app’s worker processes with autoscaling enabled back to previous values.

DELETE /maintenance

Returns (JSON):

{
  "name": "example",
  "maintenance_enabled_at": null
}

In case there’s any error from the platform trying to scale the processes up, maintenance mode will still be disabled, and we’ll return an additional errors key:

{
  "name": "example",
  "maintenance_enabled_at": null,
  "errors": ["error setting new scales: {\"worker\"=>1}"]
}

Sample Code

Here’s an example of using curl to fetch your current app settings:

export JUDOSCALE_URL=$(heroku config:get JUDOSCALE_URL)
curl $JUDOSCALE_URL/settings

Here’s how you might use Faraday to disable autoscaling on your app’s worker dynos:

api = Faraday.new ENV.fetch('JUDOSCALE_URL') do |faraday|
  faraday.request :json
  faraday.response :json
  faraday.adapter Faraday.default_adapter
end

response = api.patch('process_type', {
  process_type: {
    name: 'worker',
    autoscaling_enabled: false
  }
})

Errors

  • The API will return a 401 status for an invalid token.
  • The API will return a 422 status for invalid params.
  • All other (unexpected) errors will return a 500 status.