# List twins

Endpoint: POST /twins
Version: v3
Security: oauth2

## Request fields (application/json):

  - `modelFilter` (object)
    Model Filter Class for Get Twins Request.

  - `modelFilter.modelIds` (array)
    Array of twin model Id twins to retrieve.

  - `modelFilter.exactModelMatch` (boolean)
    True to only include twins that are instances of the exact model id specified,
False(default) to include twins that are instances of the model id or any of its subclasses.

  - `relationshipFilter` (object)
    Get Twins Request Relationship Filter

  - `relationshipFilter.relationshipDirection` (string)
    Twin Relationship Direction.
    Enum: "Incoming", "Outgoing", "IncomingOrOutgoing"

  - `relationshipFilter.relationshipNames` (array,null)
    Array of related relationship names.
    Enum: "isPartOf", "isDocumentOf", "hasDocument", "isCapabilityOf", "locatedIn", "hostedBy", "includedIn", "servedBy", "leasee", "hasLease", "locatedInGridRegion", "isParameterOf", "isFedBy", "subMeterOf", "serves", "ownedBy", "manufacturedBy", "serviceResponsibility", "installedBy", "servicedBy"

  - `relationshipFilter.relatedModelFilter` (object)
    Model Filter Class for Get Twins Request.

  - `locationFilter` (object)
    Location Filter Class for Get Twins Request.

  - `locationFilter.locationId` (string,null)
    Location Id to filter the twins.

  - `dateFilter` (object)
    Date Filter Class for Get Twins Request.

  - `dateFilter.lastUpdatedAfter` (string,null)
    Filters twins with LastUpdatedTime greater than the given date time.

  - `dateFilter.lastUpdatedBefore` (string,null)
    Filters twins with LastUpdatedTime less than the given date time.

  - `propertyFilter` (object)
    Represents a group of filter specifications. Contains a list of individual filter specifications.

  - `propertyFilter.field` (string,null)
    Gets or set the field Name.

  - `propertyFilter.operator` (string,null)
    Gets or sets the operator. Forwards the value to the base class.

  - `propertyFilter.value` (object)
    Gets or sets the value.

  - `propertyFilter.filterConditionOperator` (any)
    Enum: "And", "Or"

  - `propertyFilter.filters` (array)
    A list of filter group specifications represented by FilterSpecificationDto objects.

  - `include` (object)
    Include Option Class for Get Twins Request.

  - `include.outgoingRelationships` (boolean)
    True to include twin outgoing relationships; false otherwise.

  - `include.incomingRelationships` (boolean)
    True to include twin incoming relationships; false otherwise.

  - `pageSize` (integer)
    Maximum number of twins to return per request. Minimum is 1 and Maximum is 1000.

  - `continuationToken` (string,null)
    Continuation Token for subsequent requests. Set the Continuation token for the initial request.

## Response 200 fields (application/json):

  - `content` (array)
    Gets or sets the collection of items contained in the response.
    Example: [{"id":"TW-DD-II-L01","modelId":"dtmi:com:willowinc:Level;1","lastUpdateTime":"2024-08-30T03:49:30.4062816+00:00","contents":{"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":[{"Id":"Room-L01-100_isPartOf_TW-DD-II-L01","targetId":"TW-DD-II-L01","sourceId":"Room-L01-100","name":"isPartOf"}],"outgoingRelationships":[{"Id":"TW-DD-II-L01_isPartOf_BLDG-1","targetId":"BLDG-1","sourceId":"TW-DD-II-L01","name":"isPartOf"}]}]

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

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

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

  - `content.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"}}}

  - `content.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"}]

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

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

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

  - `content.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"

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

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

  - `continuationToken` (string,null)
    Gets or sets the continuation token used to retrieve the next page of results in a paginated operation.

## Response 400 fields (application/json):

  - `type` (string,null)

  - `title` (string,null)

  - `status` (integer,null)

  - `detail` (string,null)

  - `instance` (string,null)

  - `errors` (object)