> ## Documentation Index
> Fetch the complete documentation index at: https://docs.levelblue.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Investigations

> Returns the list of investigations. Pagination and querying
available.



## OpenAPI

````yaml /documentation/api-reference/v3.yaml get /investigations
openapi: 3.0.0
info:
  title: USM Anywhere Investigations API
  version: '3'
  description: >-
    This document contains the API specification for the Investigations
    microservice. You can use this API to build, delete, modify, or list the
    Investigation objects, which may contain attachments, evidence, or notes.
  contact:
    url: http://www.levelblue.com
servers:
  - url: http://investigations.{region}.alienvault.cloud/investigations/v3
security:
  - JWT: []
tags:
  - name: Attachments
  - name: Evidence
  - name: History
  - name: Investigations
  - name: Notes
paths:
  /investigations:
    get:
      tags:
        - Investigations
      summary: List Investigations
      description: |-
        Returns the list of investigations. Pagination and querying
        available.
      operationId: get-investigations
      parameters:
        - $ref: '#/components/parameters/X-ATT-MessageId'
        - name: fields
          in: query
          schema:
            type: string
          description: |-
            In GET operations, a consumer application may want selected
            attributes of a representation. Although the consumer can
            ignore attributes it doesn’t utilize, transferring the
            attributes wastes bandwidth and time. Hence, for performance
            reasons, the consumer wants only the attributes it uses.

            When requesting multiple fields, separate their names with commas.
            For example `fields=name,breed`

            When requesting fields from nested data structures use the name
            of the nested object and parentheses for the nested object's
            fields. For example
            `fields=name,proficiencies(sheepHerding,obedience)`

            When requesting an entire nested data structure use the name
            of the nested object. For example
            `fields=name,proficiencies`
          required: false
        - name: page
          in: query
          description: The number of the page being requested starting with 1
          schema:
            type: integer
        - name: perPage
          in: query
          description: |-
            'An integer that describes the number of objects contained in
            a page. The maximum page size is {TBD}. If a number greater
            than this is specified, the server will use the maximum page
            size instead.'
          schema:
            type: integer
        - name: q
          schema:
            type: string
          in: query
          description: RSQL query string
      responses:
        '200':
          description: OK
          headers:
            X-ATT-TransactionId:
              $ref: '#/components/headers/X-ATT-TransactionId'
            X-ATT-ServiceVersion:
              $ref: '#/components/headers/X-ATT-ServiceVersion'
            X-ATT-MessageId:
              $ref: '#/components/headers/X-ATT-MessageId'
          content:
            application/json:
              schema:
                title: getInvestigations
                type: object
                properties:
                  _links:
                    type: object
                    properties:
                      self:
                        allOf:
                          - $ref: '#/components/schemas/href'
                        description: The current page of data (or self page)
                      next:
                        allOf:
                          - $ref: '#/components/schemas/href'
                        description: |-
                          References the self page number + 1. This relation
                          will not be present if the self page is the same as
                          the last page.
                      prev:
                        allOf:
                          - $ref: '#/components/schemas/href'
                        description: |-
                          References the self page number -1. This relation will
                          not appear if the self page is the same as the first
                          page.
                      first:
                        allOf:
                          - $ref: '#/components/schemas/href'
                        description: References the first page in the sequence.
                      last:
                        allOf:
                          - $ref: '#/components/schemas/href'
                        description: References the last page in the sequence (when known).
                    required:
                      - self
                      - first
                      - last
                  investigations:
                    type: array
                    items:
                      $ref: '#/components/schemas/gInvestigation'
                  page:
                    title: PageDetail
                    type: object
                    properties:
                      number:
                        type: integer
                        description: The page number (the first page is 1)
                      pages:
                        type: integer
                        description: The number of pages in the data set
                      elements:
                        type: integer
                        description: The number of elements in the data set
                      size:
                        type: integer
                        description: The number of elements in a page
              examples:
                i11ns_get:
                  summary: Response Example - page 2 of 5
                  value:
                    _links:
                      self:
                        href: >-
                          https://svc.alienvault.cloud/investigations/v3/investigations?deployments=cn%3A%2F%2Fasecurityteam.alienvault.cloud&page=2&perPage=3
                      prev:
                        href: >-
                          https://svc.alienvault.cloud/investigations/v3/investigations?deployments=cn%3A%2F%2Fasecurityteam.alienvault.cloud&page=1&perPage=3
                      next:
                        href: >-
                          https://svc.alienvault.cloud/investigations/v3/investigations?deployments=cn%3A%2F%2Fasecurityteam.alienvault.cloud&page=3&perPage=3
                      first:
                        href: >-
                          https://svc.alienvault.cloud/investigations/v3/investigations?deployments=cn%3A%2F%2Fasecurityteam.alienvault.cloud&page=1&perPage=3
                      last:
                        href: >-
                          https://svc.alienvault.cloud/investigations/v3/investigations?deployments=cn%3A%2F%2Fasecurityteam.alienvault.cloud&page=5&perPage=3
                    page:
                      size: 3
                      totalElements: 13
                      totalPages: 5
                      number: 2
                    investigations:
                      - _links:
                          self:
                            href: >-
                              https://svc.alienvault.cloud/investigations/v3/investigations/2033c597-97d2-49f4-b3b6-c9079d46c0f2
                          attachments:
                            href: >-
                              https://svc.alienvault.cloud/investigations/v3/investigations/2033c597-97d2-49f4-b3b6-c9079d46c0f2/attachments
                          evidence:
                            href: >-
                              https://svc.alienvault.cloud/investigations/v3/investigations/2033c597-97d2-49f4-b3b6-c9079d46c0f2/evidence
                          history:
                            href: >-
                              https://svc.alienvault.cloud/investigations/v3/investigations/2033c597-97d2-49f4-b3b6-c9079d46c0f2/history
                          notes:
                            href: >-
                              https://svc.alienvault.cloud/investigations/v3/investigations/2033c597-97d2-49f4-b3b6-c9079d46c0f2/notes
                        _embedded:
                          attachments:
                            elements: 1
                          evidence:
                            elements: 6
                          notes:
                            elements: 3
                          history:
                            elements: 21
                        id: 2033c597-97d2-49f4-b3b6-c9079d46c0f2
                        i3: INV-201811-22-0023
                        title: A weird error
                        description: >-
                          I found this strange error in my logs. It could be
                          serious.
                        deployment: cn://asecurityteam.alienvault.cloud
                        private: false
                        severity: Medium
                        intent: Reconnaissance & Probing
                        status: Open
                        assignedTo: ace@some.mssp.com
                        created:
                          by: user@asecurityteam.com
                          'on': '2018-11-07T15:38:52.132Z'
                        lastModified:
                          by: user@asecurityteam.com
                          'on': '2018-11-07T15:38:52.132Z'
                      - _links:
                          self:
                            href: >-
                              https://svc.alienvault.cloud/investigations/v3/investigations/1b51359b-5b0b-4fa5-a045-4e40dfd1df58
                          attachments:
                            href: >-
                              https://svc.alienvault.cloud/investigations/v3/investigations/1b51359b-5b0b-4fa5-a045-4e40dfd1df58/attachments
                          evidence:
                            href: >-
                              https://svc.alienvault.cloud/investigations/v3/investigations/1b51359b-5b0b-4fa5-a045-4e40dfd1df58/evidence
                          history:
                            href: >-
                              https://svc.alienvault.cloud/investigations/v3/investigations/1b51359b-5b0b-4fa5-a045-4e40dfd1df58/history
                          notes:
                            href: >-
                              https://svc.alienvault.cloud/investigations/v3/investigations/1b51359b-5b0b-4fa5-a045-4e40dfd1df58/notes
                        _embedded:
                          attachments:
                            elements: 0
                          evidence:
                            elements: 1
                          notes:
                            elements: 1
                          history:
                            elements: 5
                        id: 1b51359b-5b0b-4fa5-a045-4e40dfd1df58
                        i3: INV-201811-22-0021
                        title: Something to investigate
                        description: We should probably look into this.
                        deployment: cn://asecurityteam.alienvault.cloud
                        private: false
                        severity: Low
                        intent: Environmental Awareness
                        status: In Review
                        assignedTo: user@asecurityteam.com
                        created:
                          by: user@asecurityteam.com
                          'on': '2018-11-06T10:18:33.765Z'
                        lastModified:
                          by: user@asecurityteam.com
                          'on': '2018-11-07T09:11:32.445Z'
                      - _links:
                          self:
                            href: >-
                              https://svc.alienvault.cloud/investigations/v3/investigations/e0e5c3e8-7702-464d-941a-57caea765d2d
                          attachments:
                            href: >-
                              https://svc.alienvault.cloud/investigations/v3/investigations/e0e5c3e8-7702-464d-941a-57caea765d2d/attachments
                          evidence:
                            href: >-
                              https://svc.alienvault.cloud/investigations/v3/investigations/e0e5c3e8-7702-464d-941a-57caea765d2d/evidence
                          history:
                            href: >-
                              https://svc.alienvault.cloud/investigations/v3/investigations/e0e5c3e8-7702-464d-941a-57caea765d2d/history
                          notes:
                            href: >-
                              https://svc.alienvault.cloud/investigations/v3/investigations/e0e5c3e8-7702-464d-941a-57caea765d2d/notes
                        _embedded:
                          attachments:
                            elements: 0
                          evidence:
                            elements: 13
                          notes:
                            elements: 41
                          history:
                            elements: 127
                        id: e0e5c3e8-7702-464d-941a-57caea765d2d
                        i3: INV-201811-22-0019
                        title: FIX THIS NOW!
                        description: >-
                          A critical flaw in our security that needs IMMEDIATE
                          attention!
                        deployment: cn://asecurityteam.alienvault.cloud
                        private: false
                        severity: Critical
                        intent: Delivery & Attack
                        status: Closed
                        assignedTo: ace@some.mssp.com
                        created:
                          by: user@asecurityteam.com
                          'on': '2018-11-07T14:55:02.132Z'
                        lastModified:
                          by: ace@some.mssp.com
                          'on': '2018-11-07T14:59:02.132Z'
                    _embedded: {}
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '406':
          $ref: '#/components/responses/406'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
components:
  parameters:
    X-ATT-MessageId:
      name: X-ATT-MessageId
      description: |-
        A client-provided value that uniquely identifies a client
        generated message sent to the service. This header will be
        reflected back unchanged in the response.
      in: header
      schema:
        type: string
        format: uuid
  headers:
    X-ATT-TransactionId:
      description: |-
        A service provided value that uniquely identifies a message
        returned by the service.
      schema:
        type: string
        format: uuid
      required: true
    X-ATT-ServiceVersion:
      description: |-
        Identifies the version number of the service that processed
        the request.
      schema:
        type: string
      required: true
    X-ATT-MessageId:
      description: |-
        A client-provided value that uniquely identifies a client
        generated message sent to the service. This header will be
        present in the response if the client provided one in the
        request.
      schema:
        type: string
      required: false
    Date:
      schema:
        type: string
        format: date-time
      required: true
  schemas:
    href:
      type: object
      description: An absolute URI [RFC3986]
      format: uri
      properties:
        href:
          type: string
          format: uri
          description: An absolute URI [RFC3986]
    gInvestigation:
      title: getInvestigation
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/selfLink'
            attachments:
              allOf:
                - $ref: '#/components/schemas/href'
              description: A link to the attachments associated with this investigation.
            evidence:
              allOf:
                - $ref: '#/components/schemas/href'
              description: A link to the evidence associated with this investigation.
            notes:
              allOf:
                - $ref: '#/components/schemas/href'
              description: A link to the notes associated with this investigation.
            history:
              allOf:
                - $ref: '#/components/schemas/href'
              description: A link to the change history of this investigation.
        _embedded:
          type: object
          properties:
            attachments:
              title: attachments
              type: object
              properties:
                elements:
                  type: integer
                  minimum: 0
              description: |-
                The number of associated attachments visible to the requesting
                user
            evidence:
              title: evidence
              type: object
              properties:
                elements:
                  type: integer
                  minimum: 0
              description: The number of associated evidence object
            notes:
              title: notes
              type: object
              properties:
                elements:
                  type: integer
                  minimum: 0
              description: The number of associated notes visible to the requesting user
            history:
              title: history
              type: object
              properties:
                elements:
                  type: integer
                  minimum: 0
              description: The number of changes in the investigation history
        id:
          $ref: '#/components/schemas/i11nId'
        i3:
          $ref: '#/components/schemas/i3'
        title:
          $ref: '#/components/schemas/i11nTitle'
        description:
          $ref: '#/components/schemas/description'
        deployment:
          $ref: '#/components/schemas/deployment'
        private:
          $ref: '#/components/schemas/private'
        status:
          $ref: '#/components/schemas/status'
        intent:
          $ref: '#/components/schemas/intent'
        severity:
          $ref: '#/components/schemas/severity'
        assignedTo:
          $ref: '#/components/schemas/assignedTo'
        created:
          $ref: '#/components/schemas/created'
        lastModified:
          $ref: '#/components/schemas/lastModified'
      description: Returns an investigation.
    selfLink:
      type: object
      description: References the returned resource
      allOf:
        - $ref: '#/components/schemas/href'
    i11nId:
      allOf:
        - $ref: '#/components/schemas/id'
      description: ID of the investigation.
    i3:
      type: string
      title: i3
      description: >-
        Allows you to specify an alternative identifier for the investigation so
        that it is simple to integrate with your existing systems and processes.
    i11nTitle:
      title: title
      type: string
      description: Title of the investigation.
    description:
      title: description
      type: string
      description: 'Description of the investigation. '
    deployment:
      type: string
      title: deployment
      format: uri
      description: URI of the USM Anywhere deployment.
    private:
      type: boolean
      description: >-
        Specifies the visibility of the item. This semantic is only valid when
        there exists a relationship between a USM Central deployment and a USM
        Anywhere deployment. When set to true, only the users within the same
        deployment, USM Central or USM Anywhere, can see the item; the users
        from the other deployment cannot. 
    status:
      type: string
      title: status
      enum:
        - Open
        - In Review
        - Closed
      description: Status of the investigation.
    intent:
      type: string
      title: intent
      enum:
        - Exploitation & Installation
        - Delivery & Attack
        - Reconnaissance & Probing
        - Environmental Awareness
      description: 'Intent of the investigation. '
    severity:
      type: string
      title: severity
      enum:
        - None
        - Low
        - Medium
        - High
        - Critical
      description: Severity of the investigation.
    assignedTo:
      type: string
      title: assignedTo
      format: email
      description: 'Email of the user receiving the assignment. '
    created:
      allOf:
        - $ref: '#/components/schemas/_modOnBy'
      description: 'Specifies when the resource was created and by whom. '
    lastModified:
      title: lastModified
      allOf:
        - $ref: '#/components/schemas/_modOnBy'
      description: 'Specifies when the latest modification was made and by whom. '
    errorBody:
      title: errorBody
      type: object
      properties:
        errorId:
          type: string
          description: |-
            Unique errorId in the context of an API.

            Recommendation: two hyphen-delimited subfields:
            * Domain: identifies the API, application, service or general
              category to which the error belongs.
            * Code: provides a unique numeric code within the domain.

            Examples: General-0001, DataDict-0001
        message:
          type: string
          description: Message text
        variables:
          type: array
          description: >-
            List of zero or more strings that represent the contents of the
            variables used by the message text.
          items:
            type: string
        errorUrl:
          type: string
          format: uri
          description: >-
            Hyperlink to more information about the error, including causes and
            solutions.
      required:
        - errorId
        - message
      x-examples:
        full error body:
          errorId: addressbook-0003
          message: 'Invalid input value for property %1. Valid values are: %2.'
          variables:
            - addressType
            - Home, Work, Other
          errorUrl: http://dev.att.com/apis/errors?code=addressbook-0003
        minimal error body:
          errorId: addressbook-0001
          message: Daily TPS limit exceeded.
    id:
      type: string
      title: id
      format: uuid
      description: Unique identifier of the resource.
    _modOnBy:
      title: _mod_on_by
      type: object
      description: 'Specifies when the change was made and by whom.  '
      properties:
        by:
          type: string
          format: email
          description: 'Email of the user who made the change. '
        'on':
          type: string
          format: date-time
          description: >-
            Date and time when the change was made. Accepted format is ISO-8601
            YYYY-MM-DDThh:mm:ss.sTZD. 
      required:
        - by
        - 'on'
  responses:
    '400':
      description: |-
        Bad Request - Many possible reasons associated with the request
        (form, content, etc.). Do not resubmit this request unchanged.
      headers:
        Date:
          $ref: '#/components/headers/Date'
        X-ATT-TransactionId:
          $ref: '#/components/headers/X-ATT-TransactionId'
        X-ATT-ServiceVersion:
          $ref: '#/components/headers/X-ATT-ServiceVersion'
        X-ATT-MessageId:
          $ref: '#/components/headers/X-ATT-MessageId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorBody'
    '401':
      description: |-
        Unauthorized - Authentication failed or was not provided in the
        Authorization header.
      headers:
        WWW-Authenticate:
          schema:
            type: string
            enum:
              - Bearer
        Date:
          $ref: '#/components/headers/Date'
        X-ATT-TransactionId:
          $ref: '#/components/headers/X-ATT-TransactionId'
        X-ATT-ServiceVersion:
          $ref: '#/components/headers/X-ATT-ServiceVersion'
        X-ATT-MessageId:
          $ref: '#/components/headers/X-ATT-MessageId'
    '403':
      description: |-
        Forbidden - The client has insufficient permissions to access
        the resource
      headers:
        Date:
          $ref: '#/components/headers/Date'
        X-ATT-TransactionId:
          $ref: '#/components/headers/X-ATT-TransactionId'
        X-ATT-ServiceVersion:
          $ref: '#/components/headers/X-ATT-ServiceVersion'
        X-ATT-MessageId:
          $ref: '#/components/headers/X-ATT-MessageId'
    '406':
      description: >-
        Not Acceptable - The value specified for the Accept header in the
        request is not supported. Acceptable value is "application/json".
      headers:
        Date:
          $ref: '#/components/headers/Date'
        X-ATT-TransactionId:
          $ref: '#/components/headers/X-ATT-TransactionId'
        X-ATT-ServiceVersion:
          $ref: '#/components/headers/X-ATT-ServiceVersion'
        X-ATT-MessageId:
          $ref: '#/components/headers/X-ATT-MessageId'
    '429':
      description: Too Many Requests
      headers:
        Date:
          $ref: '#/components/headers/Date'
        Retry-After:
          schema:
            type: integer
          description: |-
            Tells the user how long to wait in seconds before making
            another request in seconds.
        X-ATT-TransactionId:
          $ref: '#/components/headers/X-ATT-TransactionId'
        X-ATT-ServiceVersion:
          $ref: '#/components/headers/X-ATT-ServiceVersion'
        X-ATT-MessageId:
          $ref: '#/components/headers/X-ATT-MessageId'
    '500':
      description: |-
        Internal Sever Error - The server encountered an internal error
        or timed out. Please try again later.
      headers:
        Date:
          $ref: '#/components/headers/Date'
        X-ATT-TransactionId:
          $ref: '#/components/headers/X-ATT-TransactionId'
        X-ATT-ServiceVersion:
          $ref: '#/components/headers/X-ATT-ServiceVersion'
        X-ATT-MessageId:
          $ref: '#/components/headers/X-ATT-MessageId'
    '503':
      description: |-
        Service Unavailable - The server is currently unable to receive
        requests. Please try again later.
      headers:
        Date:
          $ref: '#/components/headers/Date'
        X-ATT-TransactionId:
          $ref: '#/components/headers/X-ATT-TransactionId'
        X-ATT-ServiceVersion:
          $ref: '#/components/headers/X-ATT-ServiceVersion'
        X-ATT-MessageId:
          $ref: '#/components/headers/X-ATT-MessageId'
  securitySchemes:
    JWT:
      type: http
      scheme: bearer

````