---
title: "List or find shopper profiles"
method: GET
path: "/v1/profiles"
tags: ["profiles"]
---

# List or find shopper profiles

`GET /v1/profiles`

## Request

- Base URL: `https://api.octaneai.com`
- URL: `https://api.octaneai.com/v1/profiles`
- Auth: HTTP bearer

## Query parameters

- `q` string, nullable
- `cursor` string, nullable: From the previous page's nextCursor
- `limit` integer
- `quiz_id` string, nullable
- `from` string, date, nullable
- `to` string, date, nullable

## Response `200`

One page of shopper profiles. Contact data requires profiles:read and is never cached.

- ProfileList
  - `data` ProfileSummary[], required: The profiles, newest last seen first
    - `id` string, required: The profile
    - `removed` boolean, required: True once the shopper's data was erased on a data-deletion request: no identities or contact values remain
    - `removed_at` string, date-time, nullable, required: When the data was erased; null otherwise
    - `email` string, nullable, required: The shopper's email, lowercase; null when none was captured or the profile was removed
    - `phone` string, nullable, required: The shopper's phone in E.164; null when none was captured or the profile was removed
    - `shopify_customer_id` string, nullable, required: The shopper's Shopify customer as a gid://shopify/Customer/<id> GID: known once they took a quiz logged in to the store or placed an order linked to a quiz session; null otherwise
    - `quizzes` ProfileQuiz[], required: The quizzes the shopper took
      - `id` string, required: The quiz
      - `name` string, required: Its name
    - `first_seen_at` string, date-time, nullable, required: The start of the shopper's first session; null when not known
    - `last_seen_at` string, date-time, required: The latest moment the shopper was seen
    - `sessions_count` integer, required: How many quiz sessions the shopper had
    - `completed_count` integer, required: How many of them completed
    - `returning` boolean, nullable, required: True when the shopper took a quiz again after we first knew them, on any device; null on a removed profile
    - `orders_count` integer, required: Orders linked to the shopper's quiz sessions
    - `spent` Money, required
      - `amount` string, required: A decimal string, as "79.97"
      - `currency` string, required: ISO 4217 code
    - `last_order_at` string, date-time, nullable, required: When the latest of them was placed; null without orders
  - `has_more` boolean, required: Whether another page follows
  - `next_cursor` string, nullable, required: Send as cursor for the next page; null on the last
  - `total` integer, required: How many profiles match
  - `returning_total` integer, nullable, required: How many of total came back; null once the total is capped
  - `total_capped` boolean: A search stops counting at 5,000: total is then that cap, read it as 5,000+

## Other responses

- `401`: The key is missing, malformed, revoked or expired.
- `403`: The store's plan has no API access, or the key lacks the scope.
- `404`: Not found
- `422`: A request parameter is invalid.
- `429`: The key's or the store's bucket is full; Retry-After says when to try again.
- `504`: The request timed out.

---

[API](https://skmtc.dev/octaneai/apis/octane-ai-merchant-api.md) - [All operations](https://skmtc.dev/octaneai/apis/octane-ai-merchant-api/llms.txt) - [OpenAPI document](https://skmtc.dev/octaneai/apis/octane-ai-merchant-api/revisions/dc2d1aa2b7c6?raw)