PingCAP Audit Log API

openapi: 3.2.0
info:
  description: '*TiDB Cloud API is in beta.*


    # Overview


    The TiDB Cloud API is a REST interface that provides you with programmatic access to manage administrative objects within TiDB Cloud.'
  title: IAM System OPEN Audit Log API
  contact: {}
  version: v1beta1
servers:
- url: https://iam.tidbapi.com/v1beta1
tags:
- name: Audit Log
paths:
  /auditLogs:
    get:
      description: Lists all console audit logs for your organization. This endpoint helps you track various behaviors and operations of users on the TiDB Cloud console. You can filter results by time range, event type, or keyword.
      tags:
      - Audit Log
      summary: List audit logs
      parameters:
      - description: The pagination token received from a previous [List audit logs](#tag/Audit-Log/paths/~1auditLogs/get) request. Use this token to retrieve the next page of results.
        name: pageToken
        in: query
        schema:
          type: string
      - description: The maximum number of audit logs to return. If not specified, at most 100 audit logs will be returned.
        name: pageSize
        in: query
        schema:
          type: integer
          default: '100'
          maximum: '100'
          minimum: '1'
      - description: Filters the results to include only audit logs created on or after this timestamp, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
        name: startTime
        in: query
        schema:
          type: string
          format: date-time
      - description: Filters the results to include only audit logs created before or at this timestamp, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
        name: endTime
        in: query
        schema:
          type: string
          format: date-time
      - description: Filters the results by specific event types. For more information, see [Console audit event types](https://docs.pingcap.com/tidbcloud/tidb-cloud-console-auditing/#console-audit-event-types).
        name: auditEventTypes
        in: query
        schema:
          type: string
      - description: Filters results to include only audit logs that contain the specified search term.
        name: keyword
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controller.queryAuditLogRsp'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controller.openApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controller.openApiError'
      x-code-samples:
      - lang: curl
        label: curl
        source: "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n  --location 'https://iam.tidbapi.com/v1beta1/auditLogs?startTime=2025-12-03T00:00:00Z'"
      operationId: getAuditLogs
      x-operation-id-source: derived
components:
  schemas:
    controller.openApiError:
      type: object
      properties:
        code:
          type: string
        error: {}
        msgPrefix:
          type: string
        status:
          type: integer
    controller.orgAuditLog:
      type: object
      properties:
        clusterId:
          description: The ID of the cluster associated with the audit event.
          type: string
          example: '1'
        clusterName:
          description: The display name of the cluster.
          type: string
          example: Cluster0
        clusterType:
          description: The plan of the cluster.
          type: string
          example: Dedicated
        details:
          description: The additional details about the audit event.
          type: string
          example: '{"port_number":"4000","tidb_node_group_id":"","tidb_quantity":"1","tidb_size":"8C16G","tier_type":"dedicated","tikv_quantity":"3","tikv_size":"8C32G","tikv_storage_size":"500"}'
        endTime:
          description: The timestamp when the operation completed, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
          type: string
          example: '2025-12-03T07:34:32Z'
        eventType:
          description: The type of the audit event.
          type: string
          example: CreateCluster
        id:
          description: The ID of the audit event.
          type: string
          example: '1234567890'
        operationEmail:
          description: The email address of the user who performed the operation.
          type: string
          example: user@test.com
        operationId:
          description: The ID of the operation that generated the audit event.
          type: string
          example: 0987654321
        operationIp:
          description: The IP address from which the operation was performed.
          type: string
          example: 0.0.0.0
        operationLoginMethod:
          description: The authentication method used when the user signed in.
          type: string
          example: google-oauth2
        operationType:
          description: The type of the operation, indicating whether the operation was performed by a user or through the API.
          type: string
          example: User
        organizationId:
          description: The ID of the organization in which the event occurred.
          type: string
          example: '1122334455'
        organizationName:
          description: The name of the organization.
          type: string
          example: Test Organization
        projectId:
          description: The ID of the project associated with the event.
          type: string
          example: '6677889900'
        projectName:
          description: The name of the project.
          type: string
          example: Test Project
        result:
          description: The outcome of the operation, such as `Success` or `Failure`.
          type: string
          example: Success
        tranceId:
          description: A trace identifier used to correlate this audit event with related system logs.
          type: string
          example: 1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p
    controller.queryAuditLogRsp:
      type: object
      properties:
        auditLogs:
          description: A list of console audit logs that match the query.
          type: array
          items:
            $ref: '#/components/schemas/controller.orgAuditLog'
          title: AuditLog
        nextPageToken:
          description: The token to retrieve the next page of results. Use this value as the `pageToken` parameter in the next request. This field is empty when there are no more pages.
          type: string
          example: 1a2b3c4d5e6f7g8h
        totalSize:
          description: The total number of console audit logs that match the query.
          type: integer
          example: 100