# Retrieve multiple twins

Retrieve twin details for the list of twin Ids included in the request body.
Any ids that do not reference valid twins will silently be omitted from the response -- no 404/NotFound will be generated.
Match response against your query to find any invalid IDs.

Endpoint: POST /twins/ids
Version: v3
Security: oauth2

## Query parameters:

  - `includeRelationships` (boolean)
    When true, the response includes the incoming and outgoing relationships

## Response 200 fields (application/json):

  - `id` (string, required)
    The unique Id of the digital twin.
    Example: "TW-DD-II-L01"

  - `modelId` (string, required)
    Digital Twin Model Identifier.
    Example: "dtmi:com:willowinc:Level;1"

  - `lastUpdateTime` (string,null)
    Timestamp when the twin was last updated in ISO 8601 format.
    Example: "2024-08-30T03:49:30.4062816+00:00"

  - `contents` (object)
    This field will contain properties and components as defined in the contents section of the DTDL definition of the twin.
    Example: {"levelNumber":0,"mappedIds":[{"exactType":"ExternalIdentity","scope":"CONNECTOR","scopeId":"CONxxxxxxxxxxx","value":"TW-CC-II-L01"},{"exactType":"FloorLevelIdentity","scope":"BUILDING","scopeId":"BLDGxxxxxxxxxxxxxxx","value":"0"},{"exactType":"ExternalIdentity","scope":"ORG","scopeId":"ORG2xxxxxxxxxxx","value":"urn:willowinc:twin:id:TW-DD-II-L01"}],"name":"Floor_1","uniqueID":"a360cf30-c112-40a1-b4b4-f65da82fa9e8","externalID":"FLRPXxxxxxxxxxxxxxxxx","code":"L01","siteID":"104bd33c-a697-4027-b6a6-677e30a53d09","alternateClassification":{"brickSchema":{"version":"1.3","code":"dtmi:org:brickschema:schema:Brick:Floor;1"}},"externalIds":{"mappingKey":"msrc:///CON5xxxxxxxxxxxxxxxx@willow-source/twin/TW-DD-II-L01"},"area":{"$metadata":{"$lastUpdateTime":"2024-08-30T03:49:30.4062816Z"}}}

  - `incomingRelationships` (array)
    Incoming relationships
    Example: [{"Id":"Room-L01-100_isPartOf_TW-DD-II-L01","targetId":"TW-DD-II-L01","sourceId":"Room-L01-100","name":"isPartOf"}]

  - `incomingRelationships.id` (string)
    The unique Id of the relationship entity.

  - `incomingRelationships.targetId` (string, required)
    The Id of the target twin.
    Example: "Chiller-1"

  - `incomingRelationships.sourceId` (string, required)
    The Id of the source twin.
    Example: "AHU-1"

  - `incomingRelationships.name` (string, required)
    The name of the relationship, which defines the type of link from source twin to target twin (e.g. isPartOf, locatedIn, servedBy, etc.. ).
    Example: "isFedBy"

  - `incomingRelationships.properties` (object)
    Additional properties of the relationship as defined in the DTDL model.
    Example: {"substance":"ChilledWater"}

  - `outgoingRelationships` (array)
    Outgoing relationships
    Example: [{"Id":"TW-DD-II-L01_isPartOf_BLDG-1","targetId":"BLDG-1","sourceId":"TW-DD-II-L01","name":"isPartOf"}]

## Response 400 fields (application/json):

  - `type` (string,null)

  - `title` (string,null)

  - `status` (integer,null)

  - `detail` (string,null)

  - `instance` (string,null)

  - `errors` (object)

## Response 403 fields (application/json):

  - `type` (string,null)

  - `title` (string,null)

  - `status` (integer,null)

  - `detail` (string,null)

  - `instance` (string,null)

## Response 404 fields (application/json):

  - `type` (string,null)

  - `title` (string,null)

  - `status` (integer,null)

  - `detail` (string,null)

  - `instance` (string,null)