Segments

Saved filters over what visitors asked and did; members with identity, and who entered or left.

Base URL https://api.showpilot.com/v1. Every call needs Authorization: Bearer <api key>; see Authentication.

List saved segments

GET /segments

Scope: segments:read. Operation id: listSegments.

Example request

curl "https://api.showpilot.com/v1/segments" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

Every segment with its current member count.

Field	Type	Always	Meaning
`items`	array of Segment	yes

Segment

Field	Type	Always	Meaning
`id`	string (uuid)	yes
`name`	string	yes
`description`	string	yes
`filter`	SegmentFilter	yes
`memberCount`	integer	yes	As of the last evaluation.
`evaluatedAt`	string or null (date-time)	yes
`createdAt`	string (date-time)	yes
`updatedAt`	string (date-time)	yes

SegmentFilter

Conditions AND together. At least one is required.

Field	Type	Always	Meaning
`asked`	string	no	Web-search syntax over what the visitor asked and said: `security OR SOC2`, `"single sign-on"`, `pricing -enterprise`.
`toursWatched`	array of string (uuid)	no	Any of these tours was watched.
`identified`	boolean	no	Has an email or a CRM contact.
`hasCrm`	boolean	no
`minIntent`	integer	no
`lastSeenWithinDays`	integer	no
`qualified`	object	no	Qualifying answers that must equal these values.
`labels`	object	no
`account`	object	no

Errors

Status	When
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

Save a segment

POST /segments

Scope: segments:write. Operation id: createSegment.

Requires Idempotency-Key. The worker evaluates it within minutes; call evaluate to run it now.

Example request

curl "https://api.showpilot.com/v1/segments" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

Status 201.

The saved segment.

Segment

Field	Type	Always	Meaning
`id`	string (uuid)	yes
`name`	string	yes
`description`	string	yes
`filter`	SegmentFilter	yes
`memberCount`	integer	yes	As of the last evaluation.
`evaluatedAt`	string or null (date-time)	yes
`createdAt`	string (date-time)	yes
`updatedAt`	string (date-time)	yes

SegmentFilter

Conditions AND together. At least one is required.

Field	Type	Always	Meaning
`asked`	string	no	Web-search syntax over what the visitor asked and said: `security OR SOC2`, `"single sign-on"`, `pricing -enterprise`.
`toursWatched`	array of string (uuid)	no	Any of these tours was watched.
`identified`	boolean	no	Has an email or a CRM contact.
`hasCrm`	boolean	no
`minIntent`	integer	no
`lastSeenWithinDays`	integer	no
`qualified`	object	no	Qualifying answers that must equal these values.
`labels`	object	no
`account`	object	no

Errors

Status	When
400	A parameter is malformed, such as a cursor this API did not issue, a limit under 1, or an unknown status. Code `invalid-request`.
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

Count a filter's members without saving it

POST /segments/preview

Scope: segments:read. Operation id: previewSegment.

Example request

curl "https://api.showpilot.com/v1/segments/preview" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

The normalised filter, its count, and a few matching visitor ids.

Field	Type	Always
`filter`	SegmentFilter	yes
`count`	integer	yes
`sampleVisitorIds`	array of string (uuid)	yes

SegmentFilter

Conditions AND together. At least one is required.

Field	Type	Always	Meaning
`asked`	string	no	Web-search syntax over what the visitor asked and said: `security OR SOC2`, `"single sign-on"`, `pricing -enterprise`.
`toursWatched`	array of string (uuid)	no	Any of these tours was watched.
`identified`	boolean	no	Has an email or a CRM contact.
`hasCrm`	boolean	no
`minIntent`	integer	no
`lastSeenWithinDays`	integer	no
`qualified`	object	no	Qualifying answers that must equal these values.
`labels`	object	no
`account`	object	no

Errors

Status	When
400	A parameter is malformed, such as a cursor this API did not issue, a limit under 1, or an unknown status. Code `invalid-request`.
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

Read a segment

GET /segments/{id}

Scope: segments:read. Operation id: getSegment.

Parameters

Name	In	Type	Meaning
`id`	path	string (uuid)

Example request

curl "https://api.showpilot.com/v1/segments/<id>" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

The segment.

Segment

Field	Type	Always	Meaning
`id`	string (uuid)	yes
`name`	string	yes
`description`	string	yes
`filter`	SegmentFilter	yes
`memberCount`	integer	yes	As of the last evaluation.
`evaluatedAt`	string or null (date-time)	yes
`createdAt`	string (date-time)	yes
`updatedAt`	string (date-time)	yes

SegmentFilter

Conditions AND together. At least one is required.

Field	Type	Always	Meaning
`asked`	string	no	Web-search syntax over what the visitor asked and said: `security OR SOC2`, `"single sign-on"`, `pricing -enterprise`.
`toursWatched`	array of string (uuid)	no	Any of these tours was watched.
`identified`	boolean	no	Has an email or a CRM contact.
`hasCrm`	boolean	no
`minIntent`	integer	no
`lastSeenWithinDays`	integer	no
`qualified`	object	no	Qualifying answers that must equal these values.
`labels`	object	no
`account`	object	no

Errors

Status	When
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
404	No object with that id in this workspace. Code `not-found`.
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

Rename a segment or change its filter

PATCH /segments/{id}

Scope: segments:write. Operation id: updateSegment.

Requires Idempotency-Key. A changed filter takes effect at the next evaluation.

Parameters

Name	In	Type	Meaning
`id`	path	string (uuid)

Example request

curl "https://api.showpilot.com/v1/segments/<id>" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

The updated segment.

Segment

Field	Type	Always	Meaning
`id`	string (uuid)	yes
`name`	string	yes
`description`	string	yes
`filter`	SegmentFilter	yes
`memberCount`	integer	yes	As of the last evaluation.
`evaluatedAt`	string or null (date-time)	yes
`createdAt`	string (date-time)	yes
`updatedAt`	string (date-time)	yes

SegmentFilter

Conditions AND together. At least one is required.

Field	Type	Always	Meaning
`asked`	string	no	Web-search syntax over what the visitor asked and said: `security OR SOC2`, `"single sign-on"`, `pricing -enterprise`.
`toursWatched`	array of string (uuid)	no	Any of these tours was watched.
`identified`	boolean	no	Has an email or a CRM contact.
`hasCrm`	boolean	no
`minIntent`	integer	no
`lastSeenWithinDays`	integer	no
`qualified`	object	no	Qualifying answers that must equal these values.
`labels`	object	no
`account`	object	no

Errors

Status	When
400	A parameter is malformed, such as a cursor this API did not issue, a limit under 1, or an unknown status. Code `invalid-request`.
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
404	No object with that id in this workspace. Code `not-found`.
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

Delete a segment and its membership history

DELETE /segments/{id}

Scope: segments:write. Operation id: deleteSegment.

Requires Idempotency-Key.

Parameters

Name	In	Type	Meaning
`id`	path	string (uuid)

Example request

curl "https://api.showpilot.com/v1/segments/<id>" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

Status 204. Deleted.

Errors

Status	When
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
404	No object with that id in this workspace. Code `not-found`.
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

Re-evaluate a segment now

POST /segments/{id}/evaluate

Scope: segments:write. Operation id: evaluateSegment.

Requires Idempotency-Key. Runs the same pass the worker runs; every visitor who entered or left gets a segment.entered / segment.left event.

Parameters

Name	In	Type	Meaning
`id`	path	string (uuid)

Example request

curl "https://api.showpilot.com/v1/segments/<id>/evaluate" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

What changed.

Field	Type	Always
`segmentId`	string (uuid)	yes
`entered`	integer	yes
`left`	integer	yes
`total`	integer	yes
`evaluatedAt`	string (date-time)	yes

Errors

Status	When
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
404	No object with that id in this workspace. Code `not-found`.
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

Who is in the segment now, with identity

GET /segments/{id}/members

Scope: segments:read. Operation id: listSegmentMembers.

Parameters

Name	In	Type	Meaning
`id`	path	string (uuid)
`limit`	query	integer	Page size, 1 to 200. Default 50.
`cursor`	query	string	The `nextCursor` from the previous page. Opaque; never build one.

Example request

curl "https://api.showpilot.com/v1/segments/<id>/members?limit=50" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

One page of members, newest entry first.

Field	Type	Always	Meaning
`items`	array of SegmentMember	yes
`nextCursor`	string or null	yes

SegmentMember

The visitor's identity as your systems need it; ShowPilot never sends anything to them.

Field	Type	Always	Meaning
`visitorId`	string (uuid)	yes
`email`	string or null	yes
`displayName`	string or null	yes
`account`	object or null	yes
`crm`	object or null	yes	Contact and company ids in the CRM you connected.
`labels`	object	yes
`intentScore`	integer	yes
`enteredAt`	string (date-time)	yes
`leftAt`	string or null (date-time)	yes
`changedAt`	string (date-time)	yes

Errors

Status	When
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
404	No object with that id in this workspace. Code `not-found`.
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

Who entered or left after a time

GET /segments/{id}/changes

Scope: segments:read. Operation id: listSegmentChanges.

The sync primitive. Pass the last nextSince you saw; each row says entered or left.

Parameters

Name	In	Type	Meaning
`id`	path	string (uuid)
`since`	query	string (date-time)
`limit`	query	integer	Page size, 1 to 200. Default 50.

Example request

curl "https://api.showpilot.com/v1/segments/<id>/changes?limit=50" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

Changes, oldest first.

Field	Type	Always	Meaning
`items`	array of object	yes
`nextSince`	string or null (date-time)	yes

SegmentMember

The visitor's identity as your systems need it; ShowPilot never sends anything to them.

Field	Type	Always	Meaning
`visitorId`	string (uuid)	yes
`email`	string or null	yes
`displayName`	string or null	yes
`account`	object or null	yes
`crm`	object or null	yes	Contact and company ids in the CRM you connected.
`labels`	object	yes
`intentScore`	integer	yes
`enteredAt`	string (date-time)	yes
`leftAt`	string or null (date-time)	yes
`changedAt`	string (date-time)	yes

Errors

Status	When
400	A parameter is malformed, such as a cursor this API did not issue, a limit under 1, or an unknown status. Code `invalid-request`.
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
404	No object with that id in this workspace. Code `not-found`.
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

On this page