Profiler HTTP API

The YourKit profiler agent provides a language-neutral HTTP API for controlling profiling and capturing snapshots. The API is RESTful in the sense that the agent's responses do not depend on the history of previous requests.

API is based on HTTP requests and JSON responses. All endpoints use POST methods and receive JSON object as a parameter in a request body. The response is always JSON object and has application/json as a Content-Type.

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal agent error.

You can use any tool to send HTTP requests, but in the examples below we will use the cURL command-line tool. We assume that the profiled application is running on a host and that the profiler agent is listening on a port. For details on configuring the port and SSL parameters, see the list of agent options.

Profiler agent always opens encrypted SSL socket. If you do not provide the SSL certificate, the agent creates a self-signed SSL certificate on the fly. To skip certificate validation, please add -k or --insecure to cURL options.

Requests

advanceGeneration
captureSnapshot
clearEventTables
forceGc
getJfrConfigs
getJvmTelemetry
getProbeActivityModes
getStatus
getTotalCreatedObjects
getTriggers
resetAllocationProfiling
resetCpuProfiling
resetExceptionProfiling
resetJfr
resetMonitorProfiling
resetTelemetry
resetThreadProfiling
setProbeActivityModes
setTriggers
startAllocationProfiling
startCpuProfiling
startExceptionProfiling
startJfr
startMonitorProfiling
startTelemetry
startThreadProfiling
stopAllocationProfiling
stopCpuProfiling
stopExceptionProfiling
stopJfr
stopMonitorProfiling
stopTelemetry
stopThreadProfiling

`POST` advanceGeneration

Advances object generation number.

Endpoint

https://host:port/yjp/api/v3/advanceGeneration

Parameters

description - String. Description associated with the generation.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/advanceGeneration \
-d '{"description" : "Hello, world"}'

`POST` captureSnapshot

Captures snapshot.

Endpoint

https://host:port/yjp/api/v3/captureSnapshot

Parameters

type - String. Snapshot type. One of performance | memory | hprof | jfr

nameFormat - String. Snapshot name format.

Available macros:

{app_name} - application name
{date} - snapshot capture date in format 'yyyy-MM-dd'
{datetime} - snapshot capture date and time in format 'yyyy-MM-dd-HH-mm'
{pid} - profiled process ID

The default format is {app_name}-{date}.

Characters not allowed in file names, if specified, will be replaced with '-'.

annotation - String. Snapshot annotation - a free-form text description stored directly in the snapshot file.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/captureSnapshot \
-d '{ "type" : "memory"}'

Response example

{
  "path" : "/home/foobar/Snapshots/DemoApp-2021-11-16.snapshot"
}

path - Absolute file path of the captured snapshot file. If a remote application is being profiled, then the path is in the file system of the remote host.

`POST` resetAllocationProfiling

Clears recorded allocations. When object allocation profiling starts, collected allocation data is cleared automatically, so you do not have to explicitly call this method in that case.

Endpoint

https://host:port/yjp/api/v3/resetAllocationProfiling

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/resetAllocationProfiling

`POST` resetCpuProfiling

Clears current results of CPU profiling in any mode, be it sampling, tracing or call counting. When CPU profiling starts, collected CPU profiling data is cleared automatically, so you do not have to explicitly call this method in that case.

Endpoint

https://host:port/yjp/api/v3/resetCpuProfiling

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/resetCpuProfiling

`POST` resetTelemetry

Clears all charts.

Endpoint

https://host:port/yjp/api/v3/resetTelemetry

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/resetTelemetry

`POST` resetThreadProfiling

Clears the collected thread profiling data and continues the thread profiling if it is active.

Endpoint

https://host:port/yjp/api/v3/resetThreadProfiling

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/resetThreadProfiling

`POST` clearEventTables

Clears event table(s) by name. If the specified tables have dependent tables, they will be cleared too.

Endpoint

https://host:port/yjp/api/v3/clearEventTables

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/clearEventTables \
-d '{"tables" : ["File", "Thread"]}'

`POST` resetExceptionProfiling

Clears recorded exceptions. When exception profiling starts, recorded exceptions are cleared automatically, so you do not have to explicitly call this method in that case.

Endpoint

https://host:port/yjp/api/v3/resetExceptionProfiling

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/resetExceptionProfiling

`POST` resetJfr

If a flight recording is running, stops it and starts a new one, otherwise does nothing.

Endpoint

https://host:port/yjp/api/v3/resetJfr

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/resetJfr

`POST` resetMonitorProfiling

Clears monitor profiling data. When monitor profiling starts, collected monitor profiling data is cleared automatically, so you do not have to explicitly call this method in that case.

Endpoint

https://host:port/yjp/api/v3/resetMonitorProfiling

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/resetMonitorProfiling

`POST` forceGc

Forces garbage collection in the profiled application.

Endpoint

https://host:port/yjp/api/v3/forceGc

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/forceGc

`POST` getJfrConfigs

Get available flight recording configurations, which can be started.

Endpoint

https://host:port/yjp/api/v3/getJfrConfigs

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/getJfrConfigs

Response example

[
  {
    "name" : "profile",
    "label" : "Profiling",
    "description" : "Low overhead configuration for profiling, typically around 2 % overhead."
  },
  {
    "name" : "default",
    "label" : "Continuous",
    "description" : "Low overhead configuration safe for continuous use in production environments, typically less than 1 % overhead."
  }
]

name - Flight recording configuration name, which can be used in startJfr request.

label - Human-readable configuration label.

description - Description of the configuration.

`POST` getJvmTelemetry

Returns current JVM telemetry.

Endpoint

https://host:port/yjp/api/v3/getJvmTelemetry

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/getJvmTelemetry

Response example

{
  "totalHeapSize" : 31172040
}

totalHeapSize - Size of JVM heap in bytes.

`POST` getProbeActivityModes

The mapping of probe class names to the probe activity mode. Mode might be on, off or auto.

Endpoint

https://host:port/yjp/api/v3/getProbeActivityModes

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/getProbeActivityModes

Response example

{
  "com.yourkit.probes.builtin.Sockets" : "auto",
  "com.yourkit.probes.builtin.Sync" : "off",
  "com.yourkit.probes.builtin.Threads" : "on"
}

`POST` getStatus

Returns the status of the profiler agent. The status describes currently running profiling modes.

Endpoint

https://host:port/yjp/api/v3/getStatus

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/getStatus

Response example

{
  "agentVersion" : "YourKit Java Profiler 2026.3.1",
  "allocationProfiling" : true,
  "allocationProfilingOptions" : {
    "mode" : "heapSampling",
    "interval" : 1024
  },
  "cpuProfiling" : true,
  "cpuProfilingOptions" : {
    "mode" : "sampling",
    "samplingOptions" : {
      "time" : "cpu",
      "intervalNs" : 20000000,
      "async" : false,
      "cpuThresholdNs" : 10000000
    }
  },
  "appName" : "DemoApp",
  "exceptionProfiling" : true,
  "jfr" : true,
  "jfrOptions" : {
    "configName" : "default",
    "maxSize" : 1073741824
  },
  "monitorProfiling" : true,
  "pid" : 1071027,
  "telemetry" : true,
  "threadProfiling" : true,
  "threadProfilingOptions" : {
    "mode" : "full"
  }
}

`POST` getTotalCreatedObjects

Statistics of object allocation profiling.

Endpoint

https://host:port/yjp/api/v3/getTotalCreatedObjects

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/getTotalCreatedObjects

Response example

{
  "count" : 25694429,
  "size" : 1481721664
}

count - Number of created objects.

size - Size in bytes.

`POST` getTriggers

Obtains current trigger description. If there are no triggers, an empty string will be returned.

Endpoint

https://host:port/yjp/api/v3/getTriggers

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/getTriggers

Response example

{
  "triggers" : ""
}

triggers - The trigger description.

`POST` setProbeActivityModes

Changes probe activity modes of the specified probes.

Endpoint

https://host:port/yjp/api/v3/setProbeActivityModes

Parameters

Mapping of probe class names to probe activity mode. It specifies the probes whose mode should be changed. If a probe is not present in the mapping, its mode will remain unchanged. Mode might be on, off or auto.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/setProbeActivityModes \
-d '{
  "com.yourkit.probes.builtin.Sockets" : "off",
  "com.yourkit.probes.builtin.Threads" : "on"
}'

`POST` setTriggers

Sets triggers.

Endpoint

https://host:port/yjp/api/v3/setTriggers

Parameters

triggers - String. Description of trigger(s).

append - Boolean. If true, the triggers will be added to the currently existing triggers. If false will be replaced.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/setTriggers \
-d '{
  "triggers" : "TimerListener delay=1h maxTriggerCount=-1\n  PrintMessage message=Hello output=stdout\n",
  "append":false
}'

`POST` startAllocationProfiling

Starts object allocation profiling. The method clears previously recorded allocation data.

Endpoint

https://host:port/yjp/api/v3/startAllocationProfiling

Parameters

mode - String. Allocation profiling mode. One of bci | counting | heapSampling

interval - Number. Allocation interval in bytes, applicable in the bci and heapSampling modes. When the total bytes allocated by a Java thread exceed the specified interval, the profiler records the allocation details.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/startAllocationProfiling \
-d '{ "mode" : "counting"}'

`POST` startCpuProfiling

Starts CPU profiling. The method clears previously recorded allocation data.

Endpoint

https://host:port/yjp/api/v3/startCpuProfiling

Parameters

mode - String. CPU profiling mode. One of sampling | tracing | callCounting

samplingOptions - Object. Options for sampling mode.

time - String. Measured time. One of cpu | wall.

async - Boolean. Enables or disables asynchronous sampling.

intervalNs - Number. Interval between thread stack samples in nanoseconds.

cpuThresholdNs - Number. CPU time in nanoseconds a thread must accumulate before stack sampling is triggered. Applies to the async sampling when measuring CPU time.

tracingOptions - Object. Options for tracing mode.

time - String. Measured time. One of cpu | wall.

withLineNumbers - Boolean. Enables or disables line number tracing.

adaptive - Boolean. Enables or disables adaptive tracing.

adaptiveMethodTimeThresholdNs - Number. Methods whose average execution time in nanoseconds is below this threshold are excluded from adaptive tracing.

adaptiveMethodCountThreshold - Number. Methods with invocation count above this threshold are excluded from adaptive tracing.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/startCpuProfiling \
-d '{ "mode" : "tracing", "tracingOptions" : {"time": "wall", "adaptive": true}}'

`POST` startExceptionProfiling

Starts exception profiling. If exception profiling is not running when this method is called, previous exception profiling data is cleared. If exception profiling is already running, this method has no effect.

Endpoint

https://host:port/yjp/api/v3/startExceptionProfiling

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/startExceptionProfiling

`POST` startJfr

Starts flight recording. If the flight recording is already running, it will reset and start anew.

Endpoint

https://host:port/yjp/api/v3/startJfr

Parameters

configName - String. Flight recording configuration name. Can be one of the names returned by getJfrConfigs

maxSize - Number. Max flight recording size in bytes. Set to 0 for unlimited size.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/startJfr \
-d '{
  "configName" : "profile",
  "maxSize": 0
}'

`POST` startMonitorProfiling

Starts monitor profiling. If monitor profiling is not running when this method is called, previous monitor profiling data is cleared. If monitor profiling is already running, this method has no effect.

Endpoint

https://host:port/yjp/api/v3/startMonitorProfiling

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/startMonitorProfiling

`POST` startTelemetry

Starts telemetry collection. If a telemetry collection is already in progress, the method has no effect.

Endpoint

https://host:port/yjp/api/v3/startTelemetry

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/startTelemetry

`POST` startThreadProfiling

Starts thread profiling. If thread profiling is already in progress, the method has no effect.

Endpoint

https://host:port/yjp/api/v3/startThreadProfiling

Parameters

mode - String. Thread profiling mode. One of full | states.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/startThreadProfiling \
-d '{ "mode" : "full"}'

`POST` stopAllocationProfiling

Stops object allocation profiling. If allocation profiling is not running, this method has no effect.

Endpoint

https://host:port/yjp/api/v3/stopAllocationProfiling

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/stopAllocationProfiling

`POST` stopCpuProfiling

Stops CPU profiling in any mode, be it sampling, tracing or call counting. If CPU profiling is not running, this method has no effect.

Endpoint

https://host:port/yjp/api/v3/stopCpuProfiling

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/stopCpuProfiling

`POST` stopExceptionProfiling

Stops exception profiling. If exception profiling is not running, this method has no effect.

Endpoint

https://host:port/yjp/api/v3/stopExceptionProfiling

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/stopExceptionProfiling

`POST` stopJfr

Stops flight recording. If the flight recording is not running, this method has no effect.

Endpoint

https://host:port/yjp/api/v3/stopJfr

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/stopJfr

`POST` stopMonitorProfiling

Stops monitor profiling. If monitor profiling is not running, this method has no effect.

Endpoint

https://host:port/yjp/api/v3/stopMonitorProfiling

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/stopMonitorProfiling

`POST` stopTelemetry

Stops telemetry collection. If a telemetry collection is already stopped, the method has no effect.

Endpoint

https://host:port/yjp/api/v3/stopTelemetry

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/stopTelemetry

`POST` stopThreadProfiling

Stops thread profiling. If thread profiling is off, the method has no effect.

Endpoint

https://host:port/yjp/api/v3/stopThreadProfiling

Parameters

No.

cURL example

curl -k -X POST https://host:port/yjp/api/v3/stopThreadProfiling

Profiler HTTP API

Requests

POST advanceGeneration

Endpoint

Parameters

cURL example

POST captureSnapshot

Endpoint

Parameters

cURL example

Response example

POST resetAllocationProfiling

Endpoint

Parameters

cURL example

POST resetCpuProfiling

Endpoint

Parameters

cURL example

POST resetTelemetry

Endpoint

Parameters

cURL example

POST resetThreadProfiling

Endpoint

Parameters

cURL example

POST clearEventTables

Endpoint

Parameters

cURL example

POST resetExceptionProfiling

Endpoint

Parameters

cURL example

POST resetJfr

Endpoint

Parameters

cURL example

POST resetMonitorProfiling

Endpoint

Parameters

cURL example

POST forceGc

Endpoint

Parameters

cURL example

POST getJfrConfigs

Endpoint

Parameters

cURL example

Response example

POST getJvmTelemetry

Endpoint

Parameters

cURL example

Response example

POST getProbeActivityModes

Endpoint

Parameters

cURL example

Response example

POST getStatus

Endpoint

Parameters

cURL example

Response example

POST getTotalCreatedObjects

Endpoint

Parameters

cURL example

Response example

POST getTriggers

Endpoint

Parameters

cURL example

Response example

POST setProbeActivityModes

Endpoint

Parameters

`POST` advanceGeneration

`POST` captureSnapshot

`POST` resetAllocationProfiling

`POST` resetCpuProfiling

`POST` resetTelemetry

`POST` resetThreadProfiling

`POST` clearEventTables

`POST` resetExceptionProfiling

`POST` resetJfr

`POST` resetMonitorProfiling

`POST` forceGc

`POST` getJfrConfigs

`POST` getJvmTelemetry

`POST` getProbeActivityModes

`POST` getStatus

`POST` getTotalCreatedObjects

`POST` getTriggers

`POST` setProbeActivityModes

`POST` setTriggers

`POST` startAllocationProfiling

`POST` startCpuProfiling

`POST` startExceptionProfiling

`POST` startJfr

`POST` startMonitorProfiling

`POST` startTelemetry

`POST` startThreadProfiling

`POST` stopAllocationProfiling

`POST` stopCpuProfiling

`POST` stopExceptionProfiling

`POST` stopJfr

`POST` stopMonitorProfiling

`POST` stopTelemetry

`POST` stopThreadProfiling