> ## Documentation Index > Fetch the complete documentation index at: https://bloodhound.specterops.io/llms.txt > Use this file to discover all available pages before exploring further. # Get platform data quality aggregate > Time series list of aggregate data quality stats for a given platform Applies to BloodHound Enterprise and CE ## OpenAPI ````yaml get /api/v2/platform/{platform_id}/data-quality-stats openapi: 3.0.3 info: title: BloodHound API contact: name: BloodHound Enterprise Support url: https://bloodhound.specterops.io/ email: support@specterops.io license: name: Apache-2.0 url: https://www.apache.org/licenses/LICENSE-2.0 version: v2 description: > This is the API that drives BloodHound Enterprise and Community Edition. Endpoint availability is denoted using the `Community` and `Enterprise` tags. Contact information listed is for BloodHound Enterprise customers. To get help with BloodHound Community Edition, please join our [Slack community](https://ghst.ly/BHSlack/). ## Authentication The BloodHound API supports two kinds of authentication: JWT bearer tokens and Signed Requests. For quick tests or one-time calls, the JWT used by your browser may be the simplest route. For more secure and long lived API integrations, the recommended option is signed requests. ### JWT Bearer Token The API will accept calls using the following header structure in the HTTP request: ``` Authorization: Bearer $JWT_TOKEN ``` If you open the Network tab within your browser, you will see calls against the API made utilizing this structure. JWT bearer tokens are supported by the BloodHound API, however it is recommended they only be used for temporary access. JWT tokens expire after a set amount of time and require re-authentication using secret credentials. ### Signed Requests Signed requests are the recommended form of authentication for the BloodHound API. Not only are signed requests better for long lived integrations, they also provide more security for the requests being sent. They provide authentication of the client, as well as verification of request integrity when received by the server. Signed requests consist of three main parts: The client token ID, the request timestamp, and a base64 encoded HMAC signature. These three pieces of information are sent with the request using the following header structure: ``` Authorization: bhesignature $TOKEN_ID RequestDate: $RFC3339_DATETIME Signature: $BASE64ENCODED_HMAC_SIGNATURE ``` To use signed requests, you will need to generate an API token. Each API token generated in the BloodHound API comes with two parts: The Token ID, which is used in the `Authorization` header, and the Token Key, which is used as part of the HMAC hashing process. The token ID should be considered as public (like a username) and the token key should be considered secret (like a password). Once an API token is generated, you can use the key to sign requests. For more documentation about how to work with authentication in the API, including examples of how to generate an API token in the BloodHound UI, please refer to this support doc: [Working with the BloodHound API](https://bloodhound.specterops.io/integrations/bloodhound-api/working-with-api). #### Signed Request Pseudo-code Example First, a digest is initiated with HMAC-SHA-256 using the token key as the digest key: ```python digester = hmac.new(sha256, api_token_key) ``` OperationKey is the first HMAC digest link in the signature chain. This prevents replay attacks that seek to modify the request method or URI. It is composed of concatenating the request method and the request URI with no delimiter and computing the HMAC digest using the token key as the digest secret: ```python # Example: GET /api/v2/test/resource HTTP/1.1 # Signature Component: GET/api/v2/test/resource digester.write(request_method + request_uri) # Update the digester for further chaining digester = hmac.New(sha256, digester.hash()) ``` DateKey is the next HMAC digest link in the signature chain. This encodes the RFC3339 formatted datetime value as part of the signature to the hour to prevent replay attacks that are older than max two hours. This value is added to the signature chain by cutting off all values from the RFC3339 formatted datetime from the hours value forward: ```python # Example: 2020-12-01T23:59:60Z # Signature Component: 2020-12-01T23 request_datetime = date.now() digester.write(request_datetime[:13]) # Update the digester for further chaining digester = hmac.New(sha256, digester.hash()) ``` Body signing is the last HMAC digest link in the signature chain. This encodes the request body as part of the signature to prevent replay attacks that seek to modify the payload of a signed request. In the case where there is no body content the HMAC digest is computed anyway, simply with no values written to the digester: ```python if request.body is not empty: digester.write(request.body) ``` Finally, base64 encode the final hash and write the three required headers before sending the request: ```python encoded_hash = base64_encode(digester.hash()) request.header.write('Authorization', 'bhesignature ' + token_id) request.header.write('RequestDate', request_datetime) request.header.write('Signature', encoded_hash) ``` servers: - url: https://your-tenant.bloodhoundenterprise.io description: >- This is the base path for all endpoints, relative to the domain where the API is being hosted. security: - JWTBearerToken: [] - SignedRequest: [] RequestDate: [] HMACSignature: [] paths: /api/v2/platform/{platform_id}/data-quality-stats: parameters: - $ref: '#/components/parameters/header.prefer' - name: platform_id description: Platform ID in: path required: true schema: type: string enum: - ad - azure get: tags: - Data Quality - Community - Enterprise summary: Get platform data quality aggregate description: Time series list of aggregate data quality stats for a given platform operationId: GetPlatformDataQualityAggregate parameters: - name: sort_by description: Sortable columns are created_at, updated_at. in: query schema: $ref: '#/components/schemas/api.params.query.sort-by' - name: start description: >- Beginning datetime of range (inclusive) in RFC-3339 format; Defaults to current datetime minus 30 days in: query schema: type: string format: date-time - name: end description: >- Ending datetime of range (exclusive) in RFC-3339 format; Defaults to current datetime in: query schema: type: string format: date-time - $ref: '#/components/parameters/query.skip' - $ref: '#/components/parameters/query.limit' responses: '200': description: OK content: application/json: schema: $ref: >- #/components/schemas/api.response.data-quality-platform-aggregate '400': $ref: '#/components/responses/bad-request' '401': $ref: '#/components/responses/unauthorized' '403': $ref: '#/components/responses/forbidden' '429': $ref: '#/components/responses/too-many-requests' '500': $ref: '#/components/responses/internal-server-error' components: parameters: header.prefer: name: Prefer description: >- Prefer header, used to specify a custom timeout in seconds using the wait parameter as per RFC7240. Passing in wait=-1 bypasses all timeout limits when the feature is enabled. in: header required: false schema: type: string default: wait=30 pattern: ^wait=(-1|[0-9]+)$ query.skip: name: skip description: >- This query parameter is used for determining the number of objects to skip in pagination. in: query schema: $ref: '#/components/schemas/api.params.query.skip' query.limit: name: limit description: >- This query parameter is used for setting an upper limit of objects returned in paginated responses. in: query schema: $ref: '#/components/schemas/api.params.query.limit' schemas: api.params.query.sort-by: type: string description: > Sort by column. Can be used multiple times; prepend a hyphen for descending order. See parameter description for details about which columns are sortable. api.response.data-quality-platform-aggregate: allOf: - $ref: '#/components/schemas/api.response.pagination' - $ref: '#/components/schemas/api.response.time-window' - type: object properties: data: type: array items: oneOf: - $ref: '#/components/schemas/model.ad-data-quality-aggregation' - $ref: '#/components/schemas/model.azure-data-quality-aggregation' api.params.query.skip: type: integer minimum: 0 description: The number of items to skip in a paginated response. api.params.query.limit: type: integer minimum: 0 description: The limit of results requested by the client. api.response.pagination: type: object properties: count: type: integer minimum: 0 description: The total number of results. skip: $ref: '#/components/schemas/api.params.query.skip' limit: $ref: '#/components/schemas/api.params.query.limit' api.response.time-window: type: object properties: start: type: string format: date-time description: The RFC-3339 timestamp to describe the beginning of a time range end: type: string format: date-time description: The RFC-3339 timestamp to describe the end of a time range model.ad-data-quality-aggregation: allOf: - $ref: '#/components/schemas/model.components.int32.id' - $ref: '#/components/schemas/model.components.timestamps' - type: object properties: domains: type: integer users: type: integer groups: type: integer computers: type: integer ous: type: integer containers: type: integer gpos: type: integer aiacas: type: integer rootcas: type: integer enterprisecas: type: integer ntauthstores: type: integer certtemplates: type: integer acls: type: integer sessions: type: integer relationships: type: integer session_completeness: type: number format: float local_group_completeness: type: number format: float run_id: type: string format: uuid model.azure-data-quality-aggregation: allOf: - $ref: '#/components/schemas/model.components.int32.id' - $ref: '#/components/schemas/model.components.timestamps' - type: object properties: tenants: type: integer users: type: integer groups: type: integer apps: type: integer service_principals: type: integer devices: type: integer management_groups: type: integer subscriptions: type: integer resource_groups: type: integer vms: type: integer key_vaults: type: integer relationships: type: integer run_id: type: string format: uuid api.error-wrapper: type: object description: '' properties: http_status: type: integer description: The HTTP status code minimum: 100 maximum: 600 timestamp: type: string format: date-time description: The RFC-3339 timestamp in which the error response was sent request_id: type: string format: uuid description: The unique identifier of the request that failed errors: type: array items: $ref: '#/components/schemas/api.error-detail' description: The error(s) that occurred from processing the request model.components.int32.id: type: object properties: id: type: integer format: int32 readOnly: true description: This is the unique identifier for this object. model.components.timestamps: type: object properties: created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true deleted_at: readOnly: true allOf: - $ref: '#/components/schemas/null.time' api.error-detail: type: object properties: context: type: string description: The context in which the error took place message: type: string description: A human-readable description of the error null.time: type: object properties: time: type: string format: date-time description: An RFC-3339 formatted string valid: description: Valid is true if `time` is not `null`. type: boolean responses: bad-request: description: > **Bad Request** This could be due to one of the following reasons: - JSON payload is missing or malformed - Path or query parameters are missing or invalid/malformed - The data sent is not valid (ex- sending a `string` in an `integer` field) content: application/json: schema: $ref: '#/components/schemas/api.error-wrapper' example: http_status: 400 timestamp: '2024-02-19T19:27:43.866Z' request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 errors: - context: clients message: The JSON payload could not be unmarshalled. unauthorized: description: > **Unauthorized** This endpoint failed an authentication requirement. Either the client tried to access a protected endpoint without being authenticated, or an auth validation failed (ex- invalid credentials or expired token). content: application/json: schema: $ref: '#/components/schemas/api.error-wrapper' example: http_status: 401 timestamp: '2024-02-19T19:27:43.866Z' request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 errors: - context: login message: Unauthorized forbidden: description: | **Forbidden** This is most commonly caused by an authenticated client trying to access a resource that it does not have permission for. content: application/json: schema: $ref: '#/components/schemas/api.error-wrapper' example: http_status: 403 timestamp: '2024-02-19T19:27:43.866Z' request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 errors: - context: clients message: You do not have permission to access this resource too-many-requests: description: | **Too Many Requests** The client has sent too many requests within a certain time window and tripped the rate limiting middleware. content: application/json: schema: $ref: '#/components/schemas/api.error-wrapper' example: http_status: 429 timestamp: '2024-02-19T19:27:43.866Z' request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 errors: - context: middleware message: Too many requests. Please try again later. internal-server-error: description: > **Internal Server Error** This is usually the result of either an unexpected database or application error. The client may try modifying or resending the request, but the error is likely not related to the client doing something wrong. content: application/json: schema: $ref: '#/components/schemas/api.error-wrapper' example: http_status: 500 timestamp: '2024-02-19T19:27:43.866Z' request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 errors: - context: clients message: >- The request could not be handled due to an unexpected database error. securitySchemes: JWTBearerToken: description: | `Authorization: Bearer $JWT_TOKEN` type: http scheme: bearer bearerFormat: JWT SignedRequest: description: | `Authorization: bhesignature $TOKEN_ID` type: apiKey name: Authorization in: header RequestDate: description: | `RequestDate: $RFC3339_DATETIME` type: apiKey name: RequestDate in: header HMACSignature: description: | `Signature: $BASE64ENCODED_HMAC_SIGNATURE` type: apiKey name: Signature in: header ````