REST ENDPOINTS /api/history

Lookup History

Every resolved lookup - from POST /api/map or the batch queue - is recorded to your account's history. These endpoints list, search, and delete it.

Authentication

AUTH OPTIONS

# Either of the following:

# 1. Personal API key (generate one at /dashboard/api-keys)
Authorization: Bearer pm_live_xxxxxxxxxxxxxxxxxxxxxxxx

# 2. Browser session (signed in via Clerk) - no header needed

List & Search

GET /api/history

Paginated, 25 results per page. search matches against both the identifier value and the product title (case-insensitive, partial match). Omit it to list everything, most recently seen first - a lookup you repeat later moves back to the top, it isn't pinned to when it was first created. seenCount and lastSeenAt track that: how many times you've looked up this exact identifier, and when you last did.

HTTP REQUEST

GET /api/history?page=1&search=nike

HTTP 200 RESPONSE

HTTP/1.1 200 OK
Content-Type: application/json

{
  "history": [
    {
      "id": "3f9e2b40-1c2a-4a3e-9c5e-7b8f2a1d9e33",
      "identifierType": "UPC",
      "identifierValue": "079361039905",
      "marketplace": "amazon",
      "marketplaceId": "B01NAL48FU",
      "title": "Nike Air Zoom Pegasus 36 Men's Running Shoes",
      "brand": "Nike",
      "price": 119.95,
      "formattedPrice": "$119.95",
      "imageUrl": "https://m.media-amazon.com/images/I/71xyz.jpg",
      "status": "success",
      "createdAt": "2026-08-27T14:02:11.000Z",
      "seenCount": 3,
      "lastSeenAt": "2026-09-10T09:18:44.000Z",
      "listingDetails": {
        "asin": "B01NAL48FU",
        "title": "Nike Air Zoom Pegasus 36 Men's Running Shoes",
        "offerCount": 6,
        "salesRank": 1420
      }
    }
  ],
  "page": 1,
  "pageSize": 25,
  "total": 1,
  "totalPages": 1
}

listingDetails is the same object POST /api/map returns under that name - trimmed here for brevity, but every field documented there is present.

Delete a Single Row

DELETE /api/history/{id}

HTTP REQUEST

DELETE /api/history/3f9e2b40-1c2a-4a3e-9c5e-7b8f2a1d9e33

HTTP 200 RESPONSE

HTTP/1.1 200 OK
Content-Type: application/json

{ "success": true }

Returns 404 if the row doesn't exist or doesn't belong to you.

Delete Everything

DELETE /api/history

HTTP REQUEST

DELETE /api/history

HTTP 200 RESPONSE

HTTP/1.1 200 OK
Content-Type: application/json

{ "success": true, "message": "History cleared successfully." }

Deletes are soft, then purged after 1 day

Both delete endpoints mark rows deleted immediately - they disappear from list results right away - rather than removing them from the database on the spot. A scheduled cleanup job permanently purges anything soft-deleted for more than 24 hours. There's no API to undo a delete before that window closes.