> ## Documentation Index
> Fetch the complete documentation index at: https://www.1password.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieves events for each usage of an item stored in a shared vault within a 1Password account

> This endpoint requires your JSON Web Token to have the *itemusages* feature.



## OpenAPI

````yaml /openapi/events_api.yaml post /api/v2/itemusages
openapi: 3.0.0
info:
  title: Events API
  description: 1Password Events API Specification.
  version: 1.4.1
servers:
  - url: https://events.1password.com
    description: 1Password
  - url: https://events.1password.ca
    description: 1Password CA
  - url: https://events.1password.eu
    description: 1Password EU
  - url: https://events.ent.1password.com
    description: 1Password Enterprise
security: []
paths:
  /api/v2/itemusages:
    post:
      tags:
        - api-v2
      summary: >-
        Retrieves events for each usage of an item stored in a shared vault
        within a 1Password account
      description: >-
        This endpoint requires your JSON Web Token to have the *itemusages*
        feature.
      operationId: getItemUsagesV2
      requestBody:
        $ref: '#/components/requestBodies/ItemUsagesRequest'
      responses:
        '200':
          $ref: '#/components/responses/ItemUsagesV2Response'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
        default:
          $ref: '#/components/responses/GenericErrorResponse'
      security:
        - jwtsa: []
components:
  requestBodies:
    ItemUsagesRequest:
      $ref: '#/components/requestBodies/CursorRequest'
    CursorRequest:
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/Cursor'
              - $ref: '#/components/schemas/ResetCursor'
          examples:
            Continuing cursor:
              $ref: '#/components/examples/Cursor'
            Resetting cursor:
              $ref: '#/components/examples/ResetCursor'
  responses:
    ItemUsagesV2Response:
      description: Item usages response object
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ItemUsageItemsV2'
    UnauthorizedErrorResponse:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerErrorResponse:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    GenericErrorResponse:
      description: Generic error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    ItemUsageItemsV2:
      description: An object wrapping cursor properties and a list of items usages
      allOf:
        - properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/ItemUsageV2'
        - $ref: '#/components/schemas/CursorCollection'
    Error:
      type: object
      properties:
        Error:
          type: object
          properties:
            Message:
              type: string
              description: The error message.
    Cursor:
      description: Cursor
      properties:
        cursor:
          description: >-
            Cursor to fetch more data if available or continue the polling
            process if required
          type: string
          example: aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK
    ResetCursor:
      description: Reset cursor
      properties:
        limit:
          type: number
          minimum: 1
          maximum: 1000
        start_time:
          $ref: '#/components/schemas/DateTimeRFC3339'
        end_time:
          $ref: '#/components/schemas/DateTimeRFC3339'
    ItemUsageV2:
      description: A single item usage object
      properties:
        uuid:
          $ref: '#/components/schemas/UUID'
        timestamp:
          $ref: '#/components/schemas/DateTimeRFC3339'
        used_version:
          type: integer
        vault_uuid:
          $ref: '#/components/schemas/UUID'
        item_uuid:
          $ref: '#/components/schemas/UUID'
        action:
          type: string
          enum:
            - fill
            - select-sso-provider
            - enter-item-edit-mode
            - export
            - share
            - secure-copy
            - reveal
            - server-create
            - server-update
            - server-fetch
          example: reveal
        user:
          $ref: '#/components/schemas/UserV2'
        client:
          $ref: '#/components/schemas/Client'
        location:
          $ref: '#/components/schemas/Location'
        account_uuid:
          $ref: '#/components/schemas/UUID'
    CursorCollection:
      description: Common cursor properties for collection responses
      allOf:
        - $ref: '#/components/schemas/Cursor'
        - properties:
            has_more:
              description: >-
                Whether there may still be more data to fetch using the returned
                cursor. If true, the subsequent request could still be empty.
              type: boolean
    DateTimeRFC3339:
      type: string
      format: date-time
      example: '2020-06-11T16:32:50-03:00'
    UUID:
      type: string
      example: 56YE2TYN2VFYRLNSHKPW5NVT5E
    UserV2:
      description: User object
      properties:
        uuid:
          $ref: '#/components/schemas/UUID'
        name:
          description: Full name
          type: string
          example: Jack O'Neill
        email:
          type: string
          format: email
        user_type:
          $ref: '#/components/schemas/SignInAttemptUserTypes'
        user_account_uuid:
          $ref: '#/components/schemas/UUID'
    Client:
      description: Metadata gathered about the client
      properties:
        app_name:
          type: string
          example: 1Password Extension
        app_version:
          type: string
          example: '20127'
        platform_name:
          type: string
          example: Chrome
        platform_version:
          description: >-
            Depending on the platform used, this can be the version of the
            browser that the client extension is installed, the model of
            computer that the native application is installed or the machine's
            CPU version that the CLI was installed
          type: string
        os_name:
          type: string
          example: MacOSX
        os_version:
          type: string
          example: 10.15.6
        ip_address:
          type: string
          example: 13.227.95.22
    Location:
      description: Geolocation Info about the client
      properties:
        country:
          type: string
          example: CA
        region:
          type: string
          example: Ontario
        city:
          type: string
          example: Toronto
        longitude:
          type: number
          example: 43.64
        latitude:
          type: number
          example: -79.433
    SignInAttemptUserTypes:
      type: string
      enum:
        - user
        - external_user
  examples:
    Cursor:
      summary: Used for continued calling with a cursor
      value:
        cursor: aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK
    ResetCursor:
      summary: Used for reseting the cursor
      value:
        limit: 100
        start_time: '2021-06-11T16:32:50-03:00'
  securitySchemes:
    jwtsa:
      type: http
      description: A JWT SA token issued to this service
      scheme: bearer
      bearerFormat: JWT-SA

````