# Get Lists Get all lists in an account. Filter to request a subset of all lists. Lists can be filtered by `id`, `name`, `created`, and `updated` fields. Returns a maximum of 10 results per page.

*Rate limits*:
Burst: `75/s`
Steady: `750/m` **Scopes:** `lists:read` [OpenAPI Spec](https://raw.githubusercontent.com/klaviyo/openapi/main/openapi/stable/apis/get_lists.json) # OpenAPI definition ```json { "openapi": "3.0.2", "info": { "title": "Lists API", "version": "2026-07-15", "description": "The Klaviyo REST API. Please visit https://developers.klaviyo.com for more details.", "contact": { "name": "Klaviyo Developer Experience Team", "email": "developers@klaviyo.com", "url": "https://developers.klaviyo.com" }, "termsOfService": "https://www.klaviyo.com/legal/api-terms", "license": { "name": "License", "url": "https://www.klaviyo.com/legal" } }, "servers": [ { "url": "https://a.klaviyo.com", "description": "Production" } ], "paths": { "/api/lists": { "get": { "operationId": "get_lists", "summary": "Get Lists", "description": "Get all lists in an account.\n\nFilter to request a subset of all lists. Lists can be filtered by `id`, `name`, `created`, and `updated` fields.\n\nReturns a maximum of 10 results per page.

*Rate limits*:
Burst: `75/s`
Steady: `750/m`\n\n**Scopes:**\n`lists:read`\n\n[OpenAPI Spec](https://raw.githubusercontent.com/klaviyo/openapi/main/openapi/stable/apis/get_lists.json)", "parameters": [ { "name": "fields[flow]", "in": "query", "description": "For more information please visit https://developers.klaviyo.com/en/v2026-07-15/reference/api-overview#sparse-fieldsets", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "archived", "created", "id", "name", "status", "trigger_type", "updated" ] } }, "explode": false }, { "name": "fields[list]", "in": "query", "description": "For more information please visit https://developers.klaviyo.com/en/v2026-07-15/reference/api-overview#sparse-fieldsets", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "created", "id", "name", "opt_in_process", "updated" ] } }, "explode": false }, { "name": "fields[tag]", "in": "query", "description": "For more information please visit https://developers.klaviyo.com/en/v2026-07-15/reference/api-overview#sparse-fieldsets", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "name" ] } }, "explode": false }, { "name": "filter", "in": "query", "description": "For more information please visit https://developers.klaviyo.com/en/v2026-07-15/reference/api-overview#filtering
Allowed field(s)/operator(s):
`name`: `any`, `equals` (string)
`id`: `any`, `equals` (string)
`created`: `greater-than` (date-time)
`updated`: `greater-than` (date-time)", "schema": { "type": "string", "example": "equals(name,['example'])" } }, { "name": "include", "in": "query", "description": "For more information please visit https://developers.klaviyo.com/en/v2026-07-15/reference/api-overview#relationships", "schema": { "type": "array", "items": { "type": "string", "enum": [ "flow-triggers", "tags" ] } }, "explode": false }, { "name": "page[cursor]", "in": "query", "description": "For more information please visit https://developers.klaviyo.com/en/v2026-07-15/reference/api-overview#pagination", "required": false, "schema": { "type": "string" } }, { "name": "page[size]", "in": "query", "description": "Default: 10. Min: 1. Max: 10.", "required": false, "schema": { "type": "integer", "default": 10, "maximum": 10, "minimum": 1 } }, { "name": "sort", "in": "query", "description": "For more information please visit https://developers.klaviyo.com/en/v2026-07-15/reference/api-overview#sorting", "schema": { "type": "string", "enum": [ "created", "-created", "id", "-id", "name", "-name", "updated", "-updated" ] } }, { "name": "revision", "in": "header", "description": "API endpoint revision (format: YYYY-MM-DD[.suffix])", "required": true, "schema": { "type": "string", "default": "2026-07-15" } } ], "responses": { "200": { "description": "Success", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/GetListListResponseCollectionCompoundDocument" } } } }, "4XX": { "$ref": "#/components/responses/ClientError" }, "5XX": { "$ref": "#/components/responses/ServerError" } }, "tags": [ "Lists" ], "x-klaviyo-filters": { "name": { "operators": { "list": [ "any", "equals" ] }, "value": { "type": "string" } }, "id": { "operators": { "list": [ "any", "equals" ], "single": [ "equals" ] }, "value": { "type": "string" } }, "created": { "operators": { "single": [ "greater-than" ] }, "value": { "type": "string", "format": "date-time" } }, "updated": { "operators": { "single": [ "greater-than" ] }, "value": { "type": "string", "format": "date-time" } } }, "x-klaviyo-pre-release": "None", "x-klaviyo-ratelimit": { "burst": "75/s", "steady": "750/m" }, "x-klaviyo-scopes": [ "lists:read" ] } } }, "components": { "schemas": { "ProfileEnum": { "type": "string", "enum": [ "profile" ] }, "FlowEnum": { "type": "string", "enum": [ "flow" ] }, "ListEnum": { "type": "string", "enum": [ "list" ] }, "SegmentEnum": { "type": "string", "enum": [ "segment" ] }, "CampaignEnum": { "type": "string", "enum": [ "campaign" ] }, "FlowActionEnum": { "type": "string", "enum": [ "flow-action" ] }, "TagEnum": { "type": "string", "enum": [ "tag" ] }, "FlowResponseObjectResource": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/FlowEnum" }, "id": { "type": "string" }, "attributes": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "archived": { "type": "boolean" }, "created": { "type": "string", "format": "date-time", "example": "2022-11-08T00:00:00+00:00" }, "updated": { "type": "string", "format": "date-time", "example": "2022-11-08T00:00:00+00:00" }, "trigger_type": { "description": "Corresponds to the object which triggered the flow.", "type": "string", "enum": [ "Added to List", "Date Based", "Low Inventory", "Metric", "Price Drop", "Unconfigured" ] } } }, "relationships": { "type": "object", "properties": { "flow-actions": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "$ref": "#/components/schemas/FlowActionEnum" }, "id": { "type": "string" } } } }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } }, "tags": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "$ref": "#/components/schemas/TagEnum" }, "id": { "type": "string" } } } }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } } } }, "links": { "$ref": "#/components/schemas/ObjectLinks" } }, "required": [ "type", "id", "attributes", "links" ] }, "TagGroupEnum": { "type": "string", "enum": [ "tag-group" ] }, "TagResponseObjectResource": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/TagEnum" }, "id": { "description": "The Tag ID", "type": "string", "example": "abcd1234-ef56-gh78-ij90-abcdef123456" }, "attributes": { "type": "object", "properties": { "name": { "description": "The Tag name", "type": "string", "example": "My Tag" } }, "required": [ "name" ] }, "relationships": { "type": "object", "properties": { "tag-group": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/TagGroupEnum" }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } }, "lists": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "$ref": "#/components/schemas/ListEnum" }, "id": { "type": "string" } } } }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } }, "segments": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "$ref": "#/components/schemas/SegmentEnum" }, "id": { "type": "string" } } } }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } }, "campaigns": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "$ref": "#/components/schemas/CampaignEnum" }, "id": { "type": "string" } } } }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } }, "flows": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "$ref": "#/components/schemas/FlowEnum" }, "id": { "type": "string" } } } }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } } } }, "links": { "$ref": "#/components/schemas/ObjectLinks" } }, "required": [ "type", "id", "attributes", "links" ] }, "ListListResponseObjectResource": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/ListEnum" }, "id": { "description": "Primary key that uniquely identifies this list. Generated by Klaviyo.", "type": "string", "example": "Y6nRLr" }, "attributes": { "type": "object", "properties": { "name": { "description": "A helpful name to label the list", "type": "string", "example": "Newsletter" }, "created": { "description": "Date and time when the list was created, in ISO 8601 format (YYYY-MM-DDTHH:MM:SS.mmmmmm)", "type": "string", "format": "date-time", "example": "2022-11-08T00:00:00+00:00" }, "updated": { "description": "Date and time when the list was last updated, in ISO 8601 format (YYYY-MM-DDTHH:MM:SS.mmmmmm)", "type": "string", "format": "date-time", "example": "2022-11-08T00:00:00+00:00" }, "opt_in_process": { "description": "The opt-in process for this list. Valid values: 'double_opt_in', 'single_opt_in'.", "type": "string", "example": "double_opt_in", "enum": [ "double_opt_in", "single_opt_in" ] } } }, "relationships": { "type": "object", "properties": { "profiles": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "$ref": "#/components/schemas/ProfileEnum" }, "id": { "type": "string" } } } }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } }, "tags": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "$ref": "#/components/schemas/TagEnum" }, "id": { "type": "string" } } } }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } }, "flow-triggers": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "$ref": "#/components/schemas/FlowEnum" }, "id": { "type": "string" } } } }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } } } }, "links": { "$ref": "#/components/schemas/ObjectLinks" } }, "required": [ "type", "id", "attributes", "links" ] }, "GetListListResponseCollectionCompoundDocument": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ListListResponseObjectResource" } }, "links": { "$ref": "#/components/schemas/CollectionLinks" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "included": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/TagResponseObjectResource" }, { "$ref": "#/components/schemas/FlowResponseObjectResource" } ] } } }, "required": [ "data" ] }, "RelationshipLinks": { "type": "object", "properties": { "self": { "type": "string", "format": "uri" }, "related": { "type": "string", "format": "uri" } }, "required": [ "self", "related" ] }, "CollectionLinks": { "type": "object", "properties": { "self": { "type": "string", "format": "uri" }, "prev": { "type": "string", "format": "uri" }, "next": { "type": "string", "format": "uri" } }, "required": [ "self" ] }, "ObjectLinks": { "type": "object", "properties": { "self": { "type": "string", "format": "uri" } }, "required": [ "self" ] }, "AgentHints": { "description": "Optional hints emitted by the API for agent callers", "type": "object", "properties": { "next_steps": { "description": "Suggested follow-up actions for agents to take after this response", "type": "array", "items": { "type": "string" } } } }, "ResponseMeta": { "description": "Response-level metadata", "type": "object", "properties": { "agent_hints": { "$ref": "#/components/schemas/AgentHints" } } } }, "responses": { "ClientError": { "description": "Client Error", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "required": [ "id", "code", "title", "detail" ], "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "title": { "type": "string" }, "detail": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" } } } } } } }, "required": [ "errors" ] } } } }, "ServerError": { "description": "Server Error", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "required": [ "id", "code", "title", "detail" ], "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "title": { "type": "string" }, "detail": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" } } } } } } }, "required": [ "errors" ] } } } } }, "securitySchemes": { "Klaviyo-API-Key": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Private key authentication for /api/ endpoints is performed by setting the `Authorization` header to `Klaviyo-API-Key your-private-api-key`
For more information please visit https://developers.klaviyo.com/en/v2026-07-15/reference/api-overview#authentication", "x-default": "Klaviyo-API-Key your-private-api-key" } } }, "tags": [ { "name": "Lists" } ], "security": [ { "Klaviyo-API-Key": [] } ], "x-readme": { "explorer-enabled": false, "proxy-enabled": true, "samples-enabled": true }, "_id": { "buffer": { "0": 106, "1": 87, "2": 133, "3": 248, "4": 182, "5": 179, "6": 234, "7": 252, "8": 177, "9": 30, "10": 99, "11": 31 } } } ```