> For the complete documentation index, see [llms.txt](https://docs.shoplift.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shoplift.ai/api-reference/public-api/list-tests.md).

# List tests

Returns paginated tests for the store. Filter by status.

```json
{"openapi":"3.1.1","info":{"title":"Shoplift Public API","version":"1.0.0"},"tags":[{"name":"Public API"}],"servers":[{"url":"https://app.shoplift.ai"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","description":"All requests require `Authorization: Bearer sl_live_<your_api_key>`. Generate a key from the Shoplift admin's API Keys settings page.","scheme":"bearer"}},"schemas":{"NullableOfExternalTestStatus":{"enum":["draft","scheduled","active","paused","suspended","incompatible","cancelled","completed",null]},"ExternalTestListResponse":{"required":["data","pagination"],"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ExternalTestItem"}},"pagination":{"$ref":"#/components/schemas/ExternalPaginationMeta"}}},"ExternalTestItem":{"required":["id","title","control","variant","status","goal","device","visitorOption","hypothesisDescription","campaign","handle","duration","period","createdAt","updatedAt","startAt","endAt","appliedAt","automaticallyStartAt","automaticallyEndAt","automaticallyPauseAt","automaticallyResumeAt","endWhenSignificant","estimatedCompletionDate","customAudiences","defaultAudiences","stage","tags","priority","surfaceArea","impact","effort","implemented"],"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"control":{"$ref":"#/components/schemas/ExternalTestControlItem"},"variant":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ExternalTestVariantItem"}]},"status":{"$ref":"#/components/schemas/ExternalTestStatus"},"goal":{"type":"string"},"device":{"type":"string"},"visitorOption":{"type":"string"},"hypothesisDescription":{"type":["null","string"]},"campaign":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ExternalCampaignRef"}]},"handle":{"type":["null","string"]},"duration":{"type":["null","number"],"format":"double"},"period":{"type":"integer","format":"int32"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"startAt":{"type":["null","string"],"format":"date-time"},"endAt":{"type":["null","string"],"format":"date-time"},"appliedAt":{"type":["null","string"],"format":"date-time"},"automaticallyStartAt":{"type":["null","string"],"format":"date-time"},"automaticallyEndAt":{"type":["null","string"],"format":"date-time"},"automaticallyPauseAt":{"type":["null","string"],"format":"date-time"},"automaticallyResumeAt":{"type":["null","string"],"format":"date-time"},"endWhenSignificant":{"type":"boolean"},"estimatedCompletionDate":{"type":["null","string"],"format":"date-time"},"customAudiences":{"type":"array","items":{"$ref":"#/components/schemas/ExternalAudienceItem"}},"defaultAudiences":{"type":"array","items":{"$ref":"#/components/schemas/ExternalDefaultAudienceItem"}},"stage":{"$ref":"#/components/schemas/ExperienceStage"},"tags":{"type":"array","items":{"$ref":"#/components/schemas/ExternalTagItem"}},"priority":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/NullableOfPriority"}]},"surfaceArea":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/NullableOfSurfaceArea"}]},"impact":{"type":["null","integer"],"format":"int32"},"effort":{"type":["null","integer"],"format":"int32"},"implemented":{"type":["null","boolean"]}}},"ExternalTestControlItem":{"required":["id","type","suffix","themeId","redirectUrl","screenshotUrl","title","traffic"],"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"suffix":{"type":"string"},"themeId":{"type":"integer","format":"int64"},"redirectUrl":{"type":["null","string"]},"screenshotUrl":{"type":["null","string"]},"title":{"type":["null","string"]},"traffic":{"type":"integer","format":"int32"}}},"ExternalTestVariantItem":{"required":["id","type","suffix","themeId","redirectUrl","screenshotUrl","title","traffic"],"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"suffix":{"type":"string"},"themeId":{"type":"integer","format":"int64"},"redirectUrl":{"type":["null","string"]},"screenshotUrl":{"type":["null","string"]},"title":{"type":["null","string"]},"traffic":{"type":"integer","format":"int32"}}},"ExternalTestStatus":{"enum":["draft","scheduled","active","paused","suspended","incompatible","cancelled","completed"]},"ExternalCampaignRef":{"required":["id","name","status"],"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"$ref":"#/components/schemas/CampaignStatus"}}},"CampaignStatus":{"enum":["active","completed"]},"ExternalAudienceItem":{"required":["id","name","rules"],"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/ExternalAudienceRuleItem"}}}},"ExternalAudienceRuleItem":{"required":["dimension","operator","values"],"type":"object","properties":{"dimension":{"type":"string"},"operator":{"type":"string"},"values":{"type":"array","items":{"type":"string"}},"selector":{"type":["null","string"]}}},"ExternalDefaultAudienceItem":{"required":["id","name","dimension","operator","value"],"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"dimension":{"type":"string"},"operator":{"type":"string"},"value":{"type":"string"}}},"ExperienceStage":{"enum":["idea","ready","scheduled","live","paused","ended"]},"ExternalTagItem":{"required":["id","name"],"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"NullableOfPriority":{"enum":["low","medium","high","critical",null]},"NullableOfSurfaceArea":{"enum":["global","homepage","pdp","plp","cart","landingPage","navigation","other",null]},"ExternalPaginationMeta":{"required":["page","perPage","totalPages","totalCount"],"type":"object","properties":{"page":{"type":"integer","format":"int32"},"perPage":{"type":"integer","format":"int32"},"totalPages":{"type":"integer","format":"int32"},"totalCount":{"type":"integer","format":"int32"}}},"ProblemDetails":{"type":"object","properties":{"type":{"type":["null","string"]},"title":{"type":["null","string"]},"status":{"type":["null","integer"],"format":"int32"},"detail":{"type":["null","string"]},"instance":{"type":["null","string"]}}}}},"paths":{"/api/public/v1/tests":{"get":{"tags":["Public API"],"summary":"List tests","description":"Returns paginated tests for the store. Filter by status.","operationId":"listTests","parameters":[{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/NullableOfExternalTestStatus"}},{"name":"page","in":"query","schema":{"type":"integer","format":"int32"}},{"name":"perPage","in":"query","schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalTestListResponse"}}}},"429":{"description":"Too Many Requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}}}
```