Pixel Accounts API

A pixel account identifies one installation of the Event Tracking Pixel. Its pixelAccountId is the customer ID that you place in the pixel script tag and send as customerId with the Event Tracking API, and it is the value the create index endpoint accepts as pixelId. Linking a pixel to an index lets the events it records feed personalization and analytics for that index.

Use this API to create pixel accounts yourself, list the ones on your account, and change the label or the linked index. Each pixel links to at most one index.

Authentication: all three endpoints take Authorization: Bearer {api_key}. A request that authenticates with x-marqo-index-id is rejected with 401 {"error": "Unauthorized"}.

note

The API key used to send events to the ingestion endpoint is separate from your Marqo API key and is not issued by this API. See Event Tracking API.

Pixel account object

Every endpoint on this page returns pixel accounts in the same shape.

{
  "pixelAccountId": "5b1f3d0e-8c2a-4f7e-9a61-2d3c4e5f6a7b",
  "label": "Web storefront",
  "indexName": "my-store-index",
  "status": "active",
  "abTestStartDate": null
}

Field	Type	Description
pixelAccountId	String	The customer ID for this pixel. Use it in the pixel script tag, as customerId on tracked events, and as pixelId when creating an index.
label	String	A name you choose for the pixel.
indexName	String or null	The index this pixel is linked to, or null when it is not linked.
status	String	active for a pixel you have just created or updated. When listing, the value comes from the pixel record.
abTestStartDate	String or null	Start date of an A/B test configured on this pixel, or null when none is set. Set by Marqo, not through this API.

List pixel accounts

Endpoint: GET https://ecom.marqo-ep.ai/api/v1/pixels

cURL

curl https://ecom.marqo-ep.ai/api/v1/pixels \
  -H "Authorization: Bearer {api_key}"

JavaScript

fetch("https://ecom.marqo-ep.ai/api/v1/pixels", {
  method: "GET",
  headers: {
    "Authorization": "Bearer {api_key}",
  },
});

Response: 200

{
  "pixels": [
    {
      "pixelAccountId": "5b1f3d0e-8c2a-4f7e-9a61-2d3c4e5f6a7b",
      "label": "Web storefront",
      "indexName": "my-store-index",
      "status": "active",
      "abTestStartDate": null
    },
    {
      "pixelAccountId": "0c9e8d7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f",
      "label": "Mobile app",
      "indexName": null,
      "status": "active",
      "abTestStartDate": null
    }
  ]
}

Only the pixel accounts that belong to your Marqo account are returned. pixels is an empty array when there are none.

Create a pixel account

Endpoint: POST https://ecom.marqo-ep.ai/api/v1/pixels

Request body

Parameter	Type	Default	Description
label	String	(required)	A name for the pixel, 1 to 200 characters.
indexName	String	null	The index to link the pixel to. Omit it to create the pixel unlinked and link it later with an update, or by passing the new pixelAccountId as pixelId when you create an index.

cURL

curl -X POST https://ecom.marqo-ep.ai/api/v1/pixels \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Web storefront",
    "indexName": "my-store-index"
  }'

JavaScript

fetch("https://ecom.marqo-ep.ai/api/v1/pixels", {
  method: "POST",
  headers: {
    "Authorization": "Bearer {api_key}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    label: "Web storefront",
    indexName: "my-store-index",
  }),
});

Response: 201

{
  "pixelAccountId": "5b1f3d0e-8c2a-4f7e-9a61-2d3c4e5f6a7b",
  "label": "Web storefront",
  "indexName": "my-store-index",
  "status": "active",
  "abTestStartDate": null
}

pixelAccountId is generated by Marqo. Install the pixel with it as described in Event Tracking Pixel:

<script src="https://pixel.marqo-ep.ai/c/5b1f3d0e-8c2a-4f7e-9a61-2d3c4e5f6a7b/p.min.js" defer></script>

A label that is missing, empty or longer than 200 characters returns 422.

Update a pixel account

Replaces the label and the index link of an existing pixel account. The body has the same fields as create, and label is required here too.

Endpoint: PUT https://ecom.marqo-ep.ai/api/v1/pixels/{pixelAccountId}

cURL

curl -X PUT https://ecom.marqo-ep.ai/api/v1/pixels/{pixelAccountId} \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Web storefront",
    "indexName": "my-new-index"
  }'

JavaScript

fetch("https://ecom.marqo-ep.ai/api/v1/pixels/{pixelAccountId}", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer {api_key}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    label: "Web storefront",
    indexName: "my-new-index",
  }),
});

Response: 200

{
  "pixelAccountId": "5b1f3d0e-8c2a-4f7e-9a61-2d3c4e5f6a7b",
  "label": "Web storefront",
  "indexName": "my-new-index",
  "status": "active",
  "abTestStartDate": null
}

Because the update replaces both fields, a request without indexName removes the index link. To move a pixel to a different index, send the new index name; the pixel is linked to one index at a time.

Related

• Event Tracking Pixel: install the script tag on your site.
• Event Tracking API: send events from your own backend or app.
• Create an index: link a pixel at creation time with pixelId.