Search for profiles in a segment

Learn more about searching for profiles in a segment.

Use the Segments to search for profiles in a segment using a scroll cursor to page through results.

HTTP method and endpoint

Use the following HTTP method and endpoint path to search for profiles in a segment.

POST {platformUrl}/api/{tenantId}/segments/{id}/entities/scan

Replace {platformUrl} with your Reltio platform base URL and {tenantId} with your tenant ID.

The following table describes the endpoint path parameters.


Parameter	Type	Required	Description
`tenantId`	String	Yes	Unique identifier of the tenant
`id`	String	Yes	Unique identifier of the segment

Query parameters

The following table describes the query parameters and their values.


Parameter	Type	Required	Description	Accepted values / Default
`sort`	String	No	The field used to sort the results.	Not stated in source
`order`	String	No	Indicates whether the profiles are sorted in ascending or descending order.	Not stated in source
`filter`	String	No	Search API filter conditions against the segment fields. Use Reltio QL syntax.	Not stated in source
`offset`	Integer	No	The pagination offset.	Not stated in source
`max`	Integer	No	The maximum number of results to return.	Not stated in source
`returnPartialResults`	Boolean	No	When set to `true` and the segment's `status` is `submitted` or `in_progress`, the response returns the data that currently exists instead of returning the `SEGMENT_NOT_EVALUATED` error. When set to `false` or omitted, the response returns profiles only after the segment has finished evaluating.	`true`, `false`; Default: `false`

Request headers

The following request headers must be included.


Header	Value	Required
`Authorization`	Bearer `<access_token>`	Yes
`Content-Type`	application/json	Yes

Request body

The request body differs between the first page and subsequent pages. For the first page, the request body must be empty. For each subsequent page, the request body contains the cursor object returned in the previous response.


Parameter	Type	Required	Description	Accepted values / Default
`cursor.value`	String	No	Opaque scroll cursor value returned by the previous response. Required for every request after the first page; omit for the first page.	Value returned by the previous response

Note: Combining returnPartialResults with a multi-page scan on a segment that has not finished evaluating can return a result set that changes between pages as evaluation continues.

Example request

The following example shows the request body for the first page. The request body is empty.

POST {platformUrl}/api/{tenantId}/segments/3prE0YZ/entities/scan

The following example shows the request body for a subsequent page, using the cursor value from the previous response.

{
  "cursor": { "value": "cXVlcnlBbmRGZXRjaDsxOzE0NDI3OmpzdTdBNGNnUWU2YlBqc1JQbTlNbnc7MDs=" }
}

Response body

The following table describes the fields returned in the response body. The last page of results returns an empty objects array.


Field	Type	Description
`cursor.value`	String	Opaque scroll cursor value to pass in the request body of the next request.
`uri`	String	Unique URI of the profile.
`type`	String	Entity type of the profile.
`createdBy`	String	Identifier of the user or service that created the profile.
`createdTime`	Long	Timestamp, in epoch milliseconds, when the profile was created.
`updatedBy`	String	Identifier of the user or service that last updated the profile.
`updatedTime`	Long	Timestamp, in epoch milliseconds, when the profile was last updated.
`attributes`	Object	The profile's attribute values.
`isFavorite`	Boolean	Indicates whether the profile is marked as a favorite.
`crosswalks`	Array	The source system crosswalk records associated with the profile.
`analyticsAttributes`	Object	Computed analytics attribute values for the profile.
`tags`	Array of String	Tags applied to the profile.
`label`	String	Display label for the profile.
`secondaryLabel`	String	Secondary display label for the profile.

Example response

The following example shows a response for the first page.

{
  "cursor" : { "value" : "cXVlcnlBbmRGZXRjaDsxOzE0NDI3OmpzdTdBNGNnUWU2YlBqc1JQbTlNbnc7MDs=" },
  "objects" : [
    { "uri" : "entities/0Fglh8Z" },
    { "uri" : "entities/0Fglh11" }
  ]
}

The following example shows the response for the last page. The objects array is empty.

{
  "cursor" : { "value" : "cXVlcnlBbmRGZXRjaDsxOzE0NDI3OmpzdTdBNGNnUWU2YlBqc1JQbTlNbnc7MDs=" },
  "objects" : []
}

Error codes and recommended actions

The following table lists the possible error responses returned by this API.


HTTP status	Error code	Description	Recommended action
`400 Bad Request`	`32006`	The segment has not finished evaluating and `returnPartialResults` was not set to `true`.	Retry the request after the segment finishes evaluating, or resend the request with `returnPartialResults` set to `true` to receive the data that currently exists.

Unify and manage your data