# Humility
URL: https://docs.datarobot.com/en/docs/api/reference/public-api/mitigation_humility.html

> Use the endpoints described below to manage humility.

# Humility

Use the endpoints described below to manage humility.

## Retrieve humility stats by deployment ID

Operation path: `GET /api/v2/deployments/{deploymentId}/humilityStats/`

Authentication requirements: `BearerAuth`

Retrieve humility rule service triggers statistics overview.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| start | query | string,null(date-time) | false | Start of the period to retrieve monitoring data, defaults to 7 days ago from the end of the period. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: 2019-08-01T00:00:00Z. |
| end | query | string,null(date-time) | false | End of the period to retrieve monitoring data, defaults to the next top of the hour. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: 2019-08-01T00:00:00Z. |
| bucketSize | query | string(duration) | false | The time duration of a bucket. Needs to be multiple of one hour. Can not be longer than the total length of the period. If not set, a default value will be calculated based on the start and end time. |
| modelId | query | string | false | The id of the model for which metrics are being retrieved. |
| segmentAttribute | query | string | false | The name of a segment attribute used for segment analysis. |
| segmentValue | query | string,null | false | The value of the segmentAttribute to segment on. |
| deploymentId | path | string | true | Unique identifier of the deployment. |

### Enumerated Values

| Parameter | Value |
| --- | --- |
| segmentAttribute | [DataRobot-Consumer, DataRobot-Remote-IP, DataRobot-Host-IP] |

### Example responses

> 200 Response

```
{
  "properties": {
    "data": {
      "description": "metrics rules",
      "items": {
        "properties": {
          "ruleId": {
            "description": "Id of the humility rule.",
            "type": "string"
          },
          "ruleName": {
            "description": "Name of the rule.",
            "type": "string"
          },
          "value": {
            "description": "Number of times the rule was triggered.",
            "type": "integer"
          }
        },
        "required": [
          "ruleId",
          "ruleName",
          "value"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "modelId": {
      "description": "The id of the model for which metrics are being retrieved.",
      "type": "string"
    },
    "period": {
      "description": "An object with the keys \"start\" and \"end\" defining the period.",
      "properties": {
        "end": {
          "description": "End of the period to retrieve monitoring data, defaults to the next top of the hour. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
          "format": "date-time",
          "type": [
            "string",
            "null"
          ]
        },
        "start": {
          "description": "Start of the period to retrieve monitoring data, defaults to 7 days ago from the end of the period. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
          "format": "date-time",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "segmentAttribute": {
      "description": "The name of the segment on which segment analysis is being performed.",
      "type": [
        "string",
        "null"
      ],
      "x-versionadded": "v2.20"
    },
    "segmentValue": {
      "default": "",
      "description": "The value of the `segmentAttribute` to segment on.",
      "type": [
        "string",
        "null"
      ],
      "x-versionadded": "v2.20"
    }
  },
  "required": [
    "data",
    "period"
  ],
  "type": "object"
}
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | OK | Humility service health statistics overview retrieved. | HumilityStatsResponse |
| 403 | Forbidden | Model Deployments and/or Monitoring are not enabled. | None |
| 404 | Not Found | Either the deployment does not exist or user does not have permission to view the deployment. | None |

## Retrieve humility stats over time by deployment ID

Operation path: `GET /api/v2/deployments/{deploymentId}/humilityStatsOverTime/`

Authentication requirements: `BearerAuth`

Retrieve humility service statistics over time.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| start | query | string,null(date-time) | false | Start of the period to retrieve monitoring data, defaults to 7 days ago from the end of the period. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: 2019-08-01T00:00:00Z. |
| end | query | string,null(date-time) | false | End of the period to retrieve monitoring data, defaults to the next top of the hour. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: 2019-08-01T00:00:00Z. |
| bucketSize | query | string(duration) | false | The time duration of a bucket. Needs to be multiple of one hour. Can not be longer than the total length of the period. If not set, a default value will be calculated based on the start and end time. |
| modelId | query | string | false | The id of the model for which metrics are being retrieved. |
| segmentAttribute | query | string | false | The name of a segment attribute used for segment analysis. |
| segmentValue | query | string,null | false | The value of the segmentAttribute to segment on. |
| deploymentId | path | string | true | Unique identifier of the deployment. |

### Enumerated Values

| Parameter | Value |
| --- | --- |
| segmentAttribute | [DataRobot-Consumer, DataRobot-Remote-IP, DataRobot-Host-IP] |

### Example responses

> 200 Response

```
{
  "properties": {
    "buckets": {
      "description": "An array of `bucket` objects, representing service health stats of the deployment over time",
      "items": {
        "description": "A `bucket` object covering whole `start`/`end` time range",
        "properties": {
          "period": {
            "description": "An object with the keys \"start\" and \"end\" defining the period.",
            "properties": {
              "end": {
                "description": "End of the period to retrieve monitoring data, defaults to the next top of the hour. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
                "format": "date-time",
                "type": [
                  "string",
                  "null"
                ]
              },
              "start": {
                "description": "Start of the period to retrieve monitoring data, defaults to 7 days ago from the end of the period. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
                "format": "date-time",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "type": "object"
          },
          "values": {
            "description": "Rules response objects.",
            "items": {
              "properties": {
                "ruleId": {
                  "description": "Id of the humility rule.",
                  "type": "string"
                },
                "ruleName": {
                  "description": "Name of the rule.",
                  "type": "string"
                },
                "value": {
                  "description": "Number of times the rule was triggered.",
                  "type": "integer"
                }
              },
              "required": [
                "ruleId",
                "ruleName",
                "value"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "period",
          "values"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "modelId": {
      "description": "The id of the model for which metrics are being retrieved.",
      "type": "string"
    },
    "segmentAttribute": {
      "description": "The name of the segment on which segment analysis is being performed.",
      "type": [
        "string",
        "null"
      ],
      "x-versionadded": "v2.20"
    },
    "segmentValue": {
      "default": "",
      "description": "The value of the `segmentAttribute` to segment on.",
      "type": [
        "string",
        "null"
      ],
      "x-versionadded": "v2.20"
    },
    "summary": {
      "description": "A `bucket` object covering whole `start`/`end` time range",
      "properties": {
        "period": {
          "description": "An object with the keys \"start\" and \"end\" defining the period.",
          "properties": {
            "end": {
              "description": "End of the period to retrieve monitoring data, defaults to the next top of the hour. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
              "format": "date-time",
              "type": [
                "string",
                "null"
              ]
            },
            "start": {
              "description": "Start of the period to retrieve monitoring data, defaults to 7 days ago from the end of the period. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
              "format": "date-time",
              "type": [
                "string",
                "null"
              ]
            }
          },
          "type": "object"
        },
        "values": {
          "description": "Rules response objects.",
          "items": {
            "properties": {
              "ruleId": {
                "description": "Id of the humility rule.",
                "type": "string"
              },
              "ruleName": {
                "description": "Name of the rule.",
                "type": "string"
              },
              "value": {
                "description": "Number of times the rule was triggered.",
                "type": "integer"
              }
            },
            "required": [
              "ruleId",
              "ruleName",
              "value"
            ],
            "type": "object"
          },
          "type": "array"
        }
      },
      "required": [
        "period",
        "values"
      ],
      "type": "object"
    }
  },
  "required": [
    "buckets",
    "summary"
  ],
  "type": "object"
}
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | OK | Humility statistics for deployment retrieved. | HumilityStatsOverTimeResponse |
| 403 | Forbidden | Model Deployments and/or Monitoring are not enabled. | None |
| 404 | Not Found | Either the deployment does not exist or user does not have permission to view the deployment. | None |

# Schemas

## HumilityStatsBucket

```
{
  "description": "A `bucket` object covering whole `start`/`end` time range",
  "properties": {
    "period": {
      "description": "An object with the keys \"start\" and \"end\" defining the period.",
      "properties": {
        "end": {
          "description": "End of the period to retrieve monitoring data, defaults to the next top of the hour. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
          "format": "date-time",
          "type": [
            "string",
            "null"
          ]
        },
        "start": {
          "description": "Start of the period to retrieve monitoring data, defaults to 7 days ago from the end of the period. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
          "format": "date-time",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "values": {
      "description": "Rules response objects.",
      "items": {
        "properties": {
          "ruleId": {
            "description": "Id of the humility rule.",
            "type": "string"
          },
          "ruleName": {
            "description": "Name of the rule.",
            "type": "string"
          },
          "value": {
            "description": "Number of times the rule was triggered.",
            "type": "integer"
          }
        },
        "required": [
          "ruleId",
          "ruleName",
          "value"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "period",
    "values"
  ],
  "type": "object"
}
```

A `bucket` object covering whole `start` / `end` time range

### Properties

| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| period | TimeRange | true |  | An object with the keys "start" and "end" defining the period. |
| values | [HumilityStatsRule] | true |  | Rules response objects. |

## HumilityStatsOverTimeResponse

```
{
  "properties": {
    "buckets": {
      "description": "An array of `bucket` objects, representing service health stats of the deployment over time",
      "items": {
        "description": "A `bucket` object covering whole `start`/`end` time range",
        "properties": {
          "period": {
            "description": "An object with the keys \"start\" and \"end\" defining the period.",
            "properties": {
              "end": {
                "description": "End of the period to retrieve monitoring data, defaults to the next top of the hour. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
                "format": "date-time",
                "type": [
                  "string",
                  "null"
                ]
              },
              "start": {
                "description": "Start of the period to retrieve monitoring data, defaults to 7 days ago from the end of the period. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
                "format": "date-time",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "type": "object"
          },
          "values": {
            "description": "Rules response objects.",
            "items": {
              "properties": {
                "ruleId": {
                  "description": "Id of the humility rule.",
                  "type": "string"
                },
                "ruleName": {
                  "description": "Name of the rule.",
                  "type": "string"
                },
                "value": {
                  "description": "Number of times the rule was triggered.",
                  "type": "integer"
                }
              },
              "required": [
                "ruleId",
                "ruleName",
                "value"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "period",
          "values"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "modelId": {
      "description": "The id of the model for which metrics are being retrieved.",
      "type": "string"
    },
    "segmentAttribute": {
      "description": "The name of the segment on which segment analysis is being performed.",
      "type": [
        "string",
        "null"
      ],
      "x-versionadded": "v2.20"
    },
    "segmentValue": {
      "default": "",
      "description": "The value of the `segmentAttribute` to segment on.",
      "type": [
        "string",
        "null"
      ],
      "x-versionadded": "v2.20"
    },
    "summary": {
      "description": "A `bucket` object covering whole `start`/`end` time range",
      "properties": {
        "period": {
          "description": "An object with the keys \"start\" and \"end\" defining the period.",
          "properties": {
            "end": {
              "description": "End of the period to retrieve monitoring data, defaults to the next top of the hour. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
              "format": "date-time",
              "type": [
                "string",
                "null"
              ]
            },
            "start": {
              "description": "Start of the period to retrieve monitoring data, defaults to 7 days ago from the end of the period. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
              "format": "date-time",
              "type": [
                "string",
                "null"
              ]
            }
          },
          "type": "object"
        },
        "values": {
          "description": "Rules response objects.",
          "items": {
            "properties": {
              "ruleId": {
                "description": "Id of the humility rule.",
                "type": "string"
              },
              "ruleName": {
                "description": "Name of the rule.",
                "type": "string"
              },
              "value": {
                "description": "Number of times the rule was triggered.",
                "type": "integer"
              }
            },
            "required": [
              "ruleId",
              "ruleName",
              "value"
            ],
            "type": "object"
          },
          "type": "array"
        }
      },
      "required": [
        "period",
        "values"
      ],
      "type": "object"
    }
  },
  "required": [
    "buckets",
    "summary"
  ],
  "type": "object"
}
```

### Properties

| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| buckets | [HumilityStatsBucket] | true |  | An array of bucket objects, representing service health stats of the deployment over time |
| modelId | string | false |  | The id of the model for which metrics are being retrieved. |
| segmentAttribute | string,null | false |  | The name of the segment on which segment analysis is being performed. |
| segmentValue | string,null | false |  | The value of the segmentAttribute to segment on. |
| summary | HumilityStatsBucket | true |  | A bucket object covering whole start/end time range |

## HumilityStatsResponse

```
{
  "properties": {
    "data": {
      "description": "metrics rules",
      "items": {
        "properties": {
          "ruleId": {
            "description": "Id of the humility rule.",
            "type": "string"
          },
          "ruleName": {
            "description": "Name of the rule.",
            "type": "string"
          },
          "value": {
            "description": "Number of times the rule was triggered.",
            "type": "integer"
          }
        },
        "required": [
          "ruleId",
          "ruleName",
          "value"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "modelId": {
      "description": "The id of the model for which metrics are being retrieved.",
      "type": "string"
    },
    "period": {
      "description": "An object with the keys \"start\" and \"end\" defining the period.",
      "properties": {
        "end": {
          "description": "End of the period to retrieve monitoring data, defaults to the next top of the hour. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
          "format": "date-time",
          "type": [
            "string",
            "null"
          ]
        },
        "start": {
          "description": "Start of the period to retrieve monitoring data, defaults to 7 days ago from the end of the period. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
          "format": "date-time",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "segmentAttribute": {
      "description": "The name of the segment on which segment analysis is being performed.",
      "type": [
        "string",
        "null"
      ],
      "x-versionadded": "v2.20"
    },
    "segmentValue": {
      "default": "",
      "description": "The value of the `segmentAttribute` to segment on.",
      "type": [
        "string",
        "null"
      ],
      "x-versionadded": "v2.20"
    }
  },
  "required": [
    "data",
    "period"
  ],
  "type": "object"
}
```

### Properties

| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| data | [HumilityStatsRule] | true |  | metrics rules |
| modelId | string | false |  | The id of the model for which metrics are being retrieved. |
| period | TimeRange | true |  | An object with the keys "start" and "end" defining the period. |
| segmentAttribute | string,null | false |  | The name of the segment on which segment analysis is being performed. |
| segmentValue | string,null | false |  | The value of the segmentAttribute to segment on. |

## HumilityStatsRule

```
{
  "properties": {
    "ruleId": {
      "description": "Id of the humility rule.",
      "type": "string"
    },
    "ruleName": {
      "description": "Name of the rule.",
      "type": "string"
    },
    "value": {
      "description": "Number of times the rule was triggered.",
      "type": "integer"
    }
  },
  "required": [
    "ruleId",
    "ruleName",
    "value"
  ],
  "type": "object"
}
```

### Properties

| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| ruleId | string | true |  | Id of the humility rule. |
| ruleName | string | true |  | Name of the rule. |
| value | integer | true |  | Number of times the rule was triggered. |

## TimeRange

```
{
  "description": "An object with the keys \"start\" and \"end\" defining the period.",
  "properties": {
    "end": {
      "description": "End of the period to retrieve monitoring data, defaults to the next top of the hour. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
      "format": "date-time",
      "type": [
        "string",
        "null"
      ]
    },
    "start": {
      "description": "Start of the period to retrieve monitoring data, defaults to 7 days ago from the end of the period. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: ``2019-08-01T00:00:00Z``.",
      "format": "date-time",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "type": "object"
}
```

An object with the keys "start" and "end" defining the period.

### Properties

| Name | Type | Required | Restrictions | Description |
| --- | --- | --- | --- | --- |
| end | string,null(date-time) | false |  | End of the period to retrieve monitoring data, defaults to the next top of the hour. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: 2019-08-01T00:00:00Z. |
| start | string,null(date-time) | false |  | Start of the period to retrieve monitoring data, defaults to 7 days ago from the end of the period. Note: this field only accepts top of the hour RFC3339 datetime strings, for example: 2019-08-01T00:00:00Z. |

---
