Skip to content
Rigel docs
Open Rigel

What we bought before

shopping.history.lookup

GET/api/v1/households/{household_id}/queries/shopping.history.lookup

  • Query
  • Rigel runs it

Recent shopping trips with what they bought, for "same as last week" and for usual amounts. For each product asked about (by ID, or every product whose name contains the text), says whether it is on the list now and when and where it was last bought, over all trips.

Parameters#

What we bought before: parameters
FieldDescription
household_idpathstringrequired

The household's ID.

product_idsqueryarray of stringsoptional

Products to report on, up to 100.

at most 100 items
textquerystringoptional

Report on every product whose name contains this, ignoring case.

1 to 120 characters
store_idquerystringoptional

Only list trips to this store. Last-bought dates still look at every store.

trip_limitqueryintegeroptional

How many recent trips to return, 1–50. Defaults to 5.

1 to 50Default 5

Response#

200 The answer.

What we bought before: response fields
FieldDescription
tripsarray of objectsrequired

Newest first.

trips[].idstringrequired

A shopping trip ID, such as trp_01JC0000000000000000000000.

trips[].storeobject or nullrequired

Where it was, or null when unknown.

trips[].store.idstringrequired

A store ID, such as sto_01JC0000000000000000000000.

trips[].store.namestringrequired

The store's name.

trips[].shopped_onstringrequired

The date, YYYY-MM-DD.

trips[].currencystring or nullrequired

ISO currency code of the prices, if any.

trips[].itemsarray of objectsrequired

What it bought, by product name.

trips[].items[].product_idstringrequired

A product ID, such as prd_01JC0000000000000000000000.

trips[].items[].product_namestringrequired

The product's name.

trips[].items[].amountstring or nullrequired

How much was bought, such as "2 lb"; null when not recorded.

trips[].items[].price_minorinteger or nullrequired

The line's price in minor units of the trip's currency.

productsarray of objectsrequired

The products asked about, by name; at most 100.

products[].product_idstringrequired

A product ID, such as prd_01JC0000000000000000000000.

products[].namestringrequired

The product's name.

products[].on_listbooleanrequired

Whether it is on the list now, checked off or not.

products[].last_boughtobject or nullrequired

The most recent trip that bought it, or null if never.

products[].last_bought.shopped_onstringrequired

The date, YYYY-MM-DD.

products[].last_bought.storeobject or nullrequired

Where, or null when unknown.

products[].last_bought.store.idstringrequired

A store ID, such as sto_01JC0000000000000000000000.

products[].last_bought.store.namestringrequired

The store's name.

Errors#

Every error has the same envelope: error.code, error.message, error.details, error.recovery and error.request_id.

What we bought before: errors
StatusCodeWhen
400validation_failedA field is missing, misspelled or out of range. details.fields lists each problem.
401unauthenticatedThe request has no valid session.
404not_foundThe household doesn't exist, or you aren't a member of it.

Examples#

These are real. Each was recorded from a sample household, the Okafors, running through the whole API when this site was built.

What we bought before

For every product whose name contains the text: whether it's on the list, and when and where it was last bought.

Request, curl
curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/shopping.history.lookup?text=milk' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/shopping.history.lookup?text=milk", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();
Request, HTTP
GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/shopping.history.lookup?text=milk HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CT9AWC6FA4A473BTDA9D

{
  "trips": [
    {
      "id": "trp_01M6V9CT8JBJVJK865ZH4D2ZZD",
      "store": {
        "id": "sto_01M6V9CT6QQBTTA6DBQXS60NCD",
        "name": "Greenway Market"
      },
      "shopped_on": "2026-11-07",
      "currency": "USD",
      "items": [
        {
          "product_id": "prd_01M6V9CT8PPECCXEW5K4JMXH06",
          "product_name": "Bananas",
          "amount": "6",
          "price_minor": 189
        },
        {
          "product_id": "prd_01M6V9CT7JAMWHZXH2HJ4HMB3Y",
          "product_name": "Crushed tomatoes",
          "amount": "2 cans",
          "price_minor": 258
        },
        {
          "product_id": "prd_01M6V9CSAWSAMCWTBQ2M7F80H9",
          "product_name": "Milk",
          "amount": "2 gallons",
          "price_minor": 778
        }
      ]
    },
    {
      "id": "trp_01M6V9CT8S4T83B9C9T7FBKE1N",
      "store": {
        "id": "sto_01M6V9CT6VGD5JCJFJBVAFR4B3",
        "name": "Pantry Direct"
      },
      "shopped_on": "2026-11-04",
      "currency": "USD",
      "items": [
        {
          "product_id": "prd_01M6V9CT8SBVFK7BC9XR4T3F4R",
          "product_name": "Dish soap",
          "amount": null,
          "price_minor": 449
        },
        {
          "product_id": "prd_01M6V9CSB4BEJEAXJPR0K7CZD9",
          "product_name": "Paper towels",
          "amount": "12 rolls",
          "price_minor": 2899
        }
      ]
    }
  ],
  "products": [
    {
      "product_id": "prd_01M6V9CSAWSAMCWTBQ2M7F80H9",
      "name": "Milk",
      "on_list": false,
      "last_bought": {
        "shopped_on": "2026-11-07",
        "store": {
          "id": "sto_01M6V9CT6QQBTTA6DBQXS60NCD",
          "name": "Greenway Market"
        }
      }
    }
  ]
}

When did we last buy these

Repeat product_ids for each product.

Request, curl
curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/shopping.history.lookup?product_ids=prd_01M6V9CSAWSAMCWTBQ2M7F80H9&product_ids=prd_01M6V9CSAG72MC7ERJ4GCZ0X7A' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/shopping.history.lookup?product_ids=prd_01M6V9CSAWSAMCWTBQ2M7F80H9&product_ids=prd_01M6V9CSAG72MC7ERJ4GCZ0X7A", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();
Request, HTTP
GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/shopping.history.lookup?product_ids=prd_01M6V9CSAWSAMCWTBQ2M7F80H9&product_ids=prd_01M6V9CSAG72MC7ERJ4GCZ0X7A HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CT9DJFGH8R2TW0XY0C26

{
  "trips": [
    {
      "id": "trp_01M6V9CT8JBJVJK865ZH4D2ZZD",
      "store": {
        "id": "sto_01M6V9CT6QQBTTA6DBQXS60NCD",
        "name": "Greenway Market"
      },
      "shopped_on": "2026-11-07",
      "currency": "USD",
      "items": [
        {
          "product_id": "prd_01M6V9CT8PPECCXEW5K4JMXH06",
          "product_name": "Bananas",
          "amount": "6",
          "price_minor": 189
        },
        {
          "product_id": "prd_01M6V9CT7JAMWHZXH2HJ4HMB3Y",
          "product_name": "Crushed tomatoes",
          "amount": "2 cans",
          "price_minor": 258
        },
        {
          "product_id": "prd_01M6V9CSAWSAMCWTBQ2M7F80H9",
          "product_name": "Milk",
          "amount": "2 gallons",
          "price_minor": 778
        }
      ]
    },
    {
      "id": "trp_01M6V9CT8S4T83B9C9T7FBKE1N",
      "store": {
        "id": "sto_01M6V9CT6VGD5JCJFJBVAFR4B3",
        "name": "Pantry Direct"
      },
      "shopped_on": "2026-11-04",
      "currency": "USD",
      "items": [
        {
          "product_id": "prd_01M6V9CT8SBVFK7BC9XR4T3F4R",
          "product_name": "Dish soap",
          "amount": null,
          "price_minor": 449
        },
        {
          "product_id": "prd_01M6V9CSB4BEJEAXJPR0K7CZD9",
          "product_name": "Paper towels",
          "amount": "12 rolls",
          "price_minor": 2899
        }
      ]
    }
  ],
  "products": [
    {
      "product_id": "prd_01M6V9CSAG72MC7ERJ4GCZ0X7A",
      "name": "Flour",
      "on_list": false,
      "last_bought": null
    },
    {
      "product_id": "prd_01M6V9CSAWSAMCWTBQ2M7F80H9",
      "name": "Milk",
      "on_list": false,
      "last_bought": {
        "shopped_on": "2026-11-07",
        "store": {
          "id": "sto_01M6V9CT6QQBTTA6DBQXS60NCD",
          "name": "Greenway Market"
        }
      }
    }
  ]
}

For Rigel#

Rigel's tool for this query is shopping_history_lookup. Rigel runs this on its own, then says what it did. The agent guide has the rest.

Rigel is in early access, and sign-up is by invitation. Open Rigel