List segments

GET /v2/marketing/segments

Returns the membership segments available to the authenticated client. Each segment in the response includes its segment_id, name, and description.

Results are paginated. Use the page and page_size query parameters to page through larger result sets. When you omit these parameters, Instacart returns the first page using the default page size.

Security

Name	In	Description
Authorization	header	The Authorization header with the client bearer token acquired during authentication.

For more information, see Get a client access token.

Parameters

Name	In	Type	Required	Description
page	query	integer		1-based page number. Must be a positive integer when supplied.
page_size	query	integer		Number of segments per page. Must be between 1 and 100 when supplied.

Request

None.

Request examples

cURL

curl --request GET \
  --url 'https://connect.instacart.com/v2/marketing/segments?page=1&page_size=1' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'

Java

HttpResponse<String> response = Unirest.get("https://connect.instacart.com/v2/marketing/segments?page=1&page_size=1")
  .header("Accept", "application/json")
  .header("Authorization", "Bearer <token>")
  .asString();

Python

import http.client

conn = http.client.HTTPSConnection("connect.instacart.com")

headers = {
    'Accept': "application/json",
    'Authorization': "Bearer <token>"
}

conn.request("GET", "/v2/marketing/segments?page=1&page_size=1", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Go

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://connect.instacart.com/v2/marketing/segments?page=1&page_size=1"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "application/json")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Response

Field	Type	Required	Description
segments	Array(Segment)		The segments on this page.
pagination	PaginationMetadata		Pagination metadata for the current result set. Omitted when the downstream response carries no pagination.

Segment Object

Field	Type	Required	Description
segment_id	string		The unique ID of the segment.
name	string		The display name of the segment.
description	string		A human-readable description of the segment.

PaginationMetadata Object

Field	Type	Required	Description
total_count	integer		The total number of segments across all pages.
page	integer		The 1-based page number of this result set.
page_size	integer		The number of segments per page.
total_pages	integer		The total number of pages available.

Response examples

200 Success

200 Success

{
  "segments": [
    {
      "segment_id": "f87414d7-1836-4b5c-84b5-6efeb2406a18",
      "name": "Loyalists",
      "description": "Top spenders"
    },
    {
      "segment_id": "a2c9e0f4-3b71-4d28-9f6a-1c5d8e2b9047",
      "name": "Lapsed",
      "description": "No order in 90 days"
    }
  ],
  "pagination": {
    "total_count": 42,
    "page": 1,
    "page_size": 20,
    "total_pages": 3
  }
}

200 Empty

{
  "segments": []
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP Code	Cause	Error Message	Error Code	Error Meta
400	Invalid page	"page must be a positive integer"	1001	Not applicable
400	Invalid page size	"page_size must be between 1 and 100"	1001	Not applicable
401	Unauthorized	"Unauthorized"	null	Not applicable
403	Forbidden	"Forbidden"	null	Not applicable