Version: 6.2

Throttling API

Important

The Throttling API is available starting with version 6.2.0.

The Throttling API lets you retrieve, create, and delete manual suppressions and exclusions for regular and SP jobs, as well as reset automatic suppressions.

Automatic suppression is configured in the job settings. The Throttling in Job Scheduler page explains automatic suppression, manual suppression, and exclusions.

Job Types

The endpoint depends on the job type:

Job type	Base endpoint
Regular job	`_core/job_scheduler/jobs/{job_id}`
SP job	`_smos/job_sp_meta/{job_id}`

SP Jobs

To manage manual suppressions and exclusions for an SP job, use _smos/job_sp_meta/{job_id}. A rule created for a child job through _core/job_scheduler/jobs/{job_id} is saved but does not apply when that child job runs as part of the SP job.

The endpoints use these parameters:

Name	Type	Description
`job_id`	`<string>`	Regular job or SP job ID
`throttle_id`	`<string>`	Manual suppression or exclusion record ID

Request Body

Manual suppressions and exclusions are created with the same request body:

Name	Type	Required	Description
`fields`	`<object>`	Yes	Search result fields and values that trigger the rule when they match
`ends_at`	`<string>`	No	Rule expiration time. If omitted, the rule remains active indefinitely

A result matches a rule if all specified field values match. If a field is absent from the result, its value is treated as the string null.

A manual suppression or exclusion can be created only when throttling is enabled in the job settings.

Request Body Requirements

The fields object must contain at least one field.

The expiration time can be an absolute date in ISO 8601 format, such as 2030-01-01T00:00:00.000Z, or a relative expression, such as now+7d. The specified time must be in the future. On save, it is converted to Unix time in seconds. Records without an expiration time do not have an ends_at field.

Example of a rule with an expiration time:

{
  "fields": {
    "host.name": "host-01"
  },
  "ends_at": "now+7d"
}

Example of a rule without an expiration time:

{
  "fields": {
    "host.name": "host-01"
  }
}

Record Structure

The retrieval operation returns manual suppression and exclusion records with these fields:

Name	Type	Description
`_meta.id`	`<string>`	Record ID, used by the delete operation
`job_id`	`<string>`	ID of the job for which the record was created
`hash`	`<int>`	Internal hash of the values in `fields`
`ends_at`	`<long>`	Rule expiration time as Unix time in seconds; absent for indefinite records
`type`	`<string>`	Record type: `suppression` for manual suppression, `exclusion` for exclusion
`origin`	`<string>`	Record origin; records returned by this API have the value `manual`
`fields`	`<object>`	Rule fields and values
`version`	`<long>`	Record format version
`sp_info.is_sp_job`	`<bool>`	Indicates an SP job record
`sp_info.parent_job_id`	`<string>`	SP job ID; present only for SP job records

Retrieve Manual Records

The operation returns up to 1,000 active manual suppression and exclusion records. Automatically created records are not included in the response.

Job type	Request
Regular job	`GET _core/job_scheduler/jobs/{job_id}/throttling`
SP job	`GET _smos/job_sp_meta/{job_id}/throttling`

Example for a regular job

Request example: retrieve manual records
GET _core/job_scheduler/jobs/job-1/throttling

Example for an SP job

Request example: retrieve manual records
GET _smos/job_sp_meta/sp-job-1/throttling

Example of a successful response (200):

[
  {
    "_meta": {
      "id": "G7G2aZsBv3Pq8tF2Qw0X"
    },
    "job_id": "job-1",
    "hash": 123456789,
    "ends_at": 1893456000,
    "type": "suppression",
    "origin": "manual",
    "fields": {
      "host.name": "host-01"
    },
    "version": 1,
    "sp_info": {
      "is_sp_job": false
    }
  }
]

Create a Manual Suppression

The operation creates a manual suppression rule or extends an existing one.

Job type	Request
Regular job	`POST _core/job_scheduler/jobs/{job_id}/throttling`
SP job	`POST _smos/job_sp_meta/{job_id}/throttling`

Send the request body. Rules of the same type with identical fields and values are considered matches. If a rule already exists, its ID is retained, and its expiration time can only be extended. If either the existing or new rule has no expiration time, the resulting rule also has no expiration time. To shorten the duration or set an expiration time on an indefinite rule, delete the existing rule and create a new one.

Example for a regular job

Request example: create a manual suppression
POST _core/job_scheduler/jobs/job-1/throttling
{
  "fields": {
    "host.name": "host-01"
  },
  "ends_at": "now+7d"
}

Example for an SP job

Request example: create a manual suppression
POST _smos/job_sp_meta/sp-job-1/throttling
{
  "fields": {
    "host.name": "host-01"
  },
  "ends_at": "now+7d"
}

Example of a successful response (200):

{
  "message": "throttling was created successfully",
  "id": "G7G2aZsBv3Pq8tF2Qw0X"
}

The id field contains the ID of the created or extended record.

Create an Exclusion

The operation creates an exclusion rule that allows a result to be processed even if it matches an automatic or manual suppression.

Job type	Request
Regular job	`POST _core/job_scheduler/jobs/{job_id}/throttling/exclusions`
SP job	`POST _smos/job_sp_meta/{job_id}/throttling/exclusions`

Send the request body. Rules of the same type with identical fields and values are considered matches. If such an exclusion already exists, its ID is retained, and its expiration time can only be extended. If either the existing or new exclusion has no expiration time, the resulting exclusion also has no expiration time. To shorten its duration or set an expiration time on an indefinite exclusion, delete it and create a new one. The successful response has the same format as for creating a manual suppression.

Example for a regular job

Request example: create an exclusion
POST _core/job_scheduler/jobs/job-1/throttling/exclusions
{
  "fields": {
    "host.name": "host-01"
  }
}

Example for an SP job

Request example: create an exclusion
POST _smos/job_sp_meta/sp-job-1/throttling/exclusions
{
  "fields": {
    "host.name": "host-01"
  }
}

Delete a Manual Record

The operation deletes a manual suppression or exclusion record by its ID. It cannot delete an automatic record.

Job type	Request
Regular job	`DELETE _core/job_scheduler/jobs/{job_id}/throttling/{throttle_id}`
SP job	`DELETE _smos/job_sp_meta/{job_id}/throttling/{throttle_id}`

Example for a regular job

Request example: delete a manual record
DELETE _core/job_scheduler/jobs/job-1/throttling/G7G2aZsBv3Pq8tF2Qw0X

Example for an SP job

Request example: delete a manual record
DELETE _smos/job_sp_meta/sp-job-1/throttling/G7G2aZsBv3Pq8tF2Qw0X

Example of a successful response (200):

"Throttle entry was deleted"

Reset Automatic Suppressions

For a regular job, the operation deletes its automatic records. For an SP job, it deletes the automatic records of all child jobs. Manual suppressions and exclusions remain.

Job type	Request
Regular job	`POST _core/job_scheduler/jobs/{job_id}/reset_throttling`
SP job	`POST _smos/job_sp_meta/{job_id}/reset_throttling`

No request body is required.

Example for a regular job

Request example: reset automatic suppressions
POST _core/job_scheduler/jobs/job-1/reset_throttling

Example for an SP job

Request example: reset automatic suppressions
POST _smos/job_sp_meta/sp-job-1/reset_throttling

Example of a successful response (200):

"Throttling for job with id 'job-1' was reset"

Job Types​

Request Body​

Record Structure​

Retrieve Manual Records​

Create a Manual Suppression​

Create an Exclusion​

Delete a Manual Record​

Reset Automatic Suppressions​

Job Types

Request Body

Record Structure

Retrieve Manual Records

Create a Manual Suppression

Create an Exclusion

Delete a Manual Record

Reset Automatic Suppressions