---
updatedAt: 2026-08-02T18:40:31.000Z
agentTools:
  projectIndex: https://hub.locally.com/llms.txt
---

# Report Index

## Request Parameters

*🏷️ header · 🔗 path · unmarked parameters are query params*

| Parameter               | Type   | Required | Description                                                                                   |
| ----------------------- | ------ | -------- | --------------------------------------------------------------------------------------------- |
| `Locally-Api-Token` 🏷️ | string | No       | Locally issued API key.                                                                       |
| `uuid` 🔗               | string | Yes      | Locally issued unique identifier for this report. Ex. `b5ed7f10-f632-11ed-b67e-0242ac120002`. |

## Example Request

```curl cURL
curl 'https://www.locally.com/api/v2/reports/json/{{REPORT_UUID}}' \
--header 'Locally-Api-Token: {{API_TOKEN}}'
```
```javascript JavaScript
const response = await fetch(
  'https://www.locally.com/api/v2/reports/json/{{REPORT_UUID}}',
  {
    headers: {
      'Locally-Api-Token': '{{API_TOKEN}}'
    }
  }
);
const data = await response.json();
```
```python Python
import requests

response = requests.get(
    'https://www.locally.com/api/v2/reports/json/{{REPORT_UUID}}',
    headers={'Locally-Api-Token': '{{API_TOKEN}}'}
)
data = response.json()
```

Each entry in `content` is a split (one store) of the report: `split_name` is the split identifier, and `first_page` plus `total_pages` tell you which Report Page URLs to fetch to download the split's full data.

## Example Response

```json JSON
{
  "version": 2,
  "status": true,
  "properties": {
    "uuid": "b5ed7f10-f632-11ed-b67e-0242ac120002",
    "report_date": "2023-05-19"
  },
  "content": [
    {
      "split_name": "1",
      "first_page": "https://www.locally.com/api/v2/reports/json/b5ed7f10-f632-11ed-b67e-0242ac120002/1/0",
      "total_pages": 94
    },
    {
      "split_name": "2",
      "first_page": "https://www.locally.com/api/v2/reports/json/b5ed7f10-f632-11ed-b67e-0242ac120002/2/0",
      "total_pages": 15
    },
    {
      "split_name": "4",
      "first_page": "https://www.locally.com/api/v2/reports/json/b5ed7f10-f632-11ed-b67e-0242ac120002/4/0",
      "total_pages": 69
    }
  ]
}
```

## Response Explanation

* `version` — Reports API format version; `2` identifies the current report system.
* `status` — `true` on success. Failures (invalid token, no access to this report, report data missing) still return HTTP `200` but with `status: false` and a `message` string.
* `properties.report_date` — Date the report was last generated — the same `uuid` always serves the newest run. Reports regenerate daily or weekly depending on report type.
* `content[].split_name` — Identifier of one split (segment) of the report. For ShopSense reports each split is one store, and `split_name` is that store's Locally store ID.
* `content[].first_page` — Ready-made [Report Page](https://hub.locally.com/lcly/docs/report-page) URL for page `0` of this split; replace the trailing page number to fetch the following pages.
* `content[].total_pages` — Page count for the split at 100 rows per page; fetch pages `0` through `total_pages - 1` to download it in full — see [Download a Full ShopSense Report](https://hub.locally.com/lcly/docs/how-to-programmatically-download-a-full-report).

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "base-server-api",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://www.locally.com/api/v2"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/reports/json/{uuid}": {
      "get": {
        "summary": "Report Index",
        "description": "",
        "operationId": "report-index",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "description": "Locally issued unique identifier for this report",
            "schema": {
              "type": "string",
              "default": "b5ed7f10-f632-11ed-b67e-0242ac120002"
            },
            "required": true
          },
          {
            "name": "Locally-Api-Token",
            "in": "header",
            "description": "Locally issued API key",
            "schema": {
              "type": "string",
              "default": "21eeed3747a24ab478c50f21b97049ed30cd9999"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n  \"version\": 2,\n  \"status\": true,\n  \"properties\": {\n    \"uuid\": \"b5ed7f10-f632-11ed-b67e-0242ac120002\",\n    \"report_date\": \"2023-05-19\"\n  },\n  \"content\": [\n    {\n      \"split_name\": \"1\",\n      \"first_page\": \"https://www.locally.com/api/v2/reports/json/b5ed7f10-f632-11ed-b67e-0242ac120002/1/0\",\n      \"total_pages\": 94\n    },\n    {\n      \"split_name\": \"2\",\n      \"first_page\": \"https://www.locally.com/api/v2/reports/json/b5ed7f10-f632-11ed-b67e-0242ac120002/2/0\",\n      \"total_pages\": 15\n    },\n    {\n      \"split_name\": \"4\",\n      \"first_page\": \"https://www.locally.com/api/v2/reports/json/b5ed7f10-f632-11ed-b67e-0242ac120002/4/0\",\n      \"total_pages\": 69\n    }\n  ]\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "version": {
                      "type": "integer",
                      "example": 2,
                      "default": 0
                    },
                    "status": {
                      "type": "boolean",
                      "example": true,
                      "default": true
                    },
                    "properties": {
                      "type": "object",
                      "properties": {
                        "uuid": {
                          "type": "string",
                          "example": "b5ed7f10-f632-11ed-b67e-0242ac120002"
                        },
                        "report_date": {
                          "type": "string",
                          "example": "2023-05-19"
                        }
                      }
                    },
                    "content": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "split_name": {
                            "type": "string",
                            "example": "1"
                          },
                          "first_page": {
                            "type": "string",
                            "example": "https://www.locally.com/api/v2/reports/json/b5ed7f10-f632-11ed-b67e-0242ac120002/1/0"
                          },
                          "total_pages": {
                            "type": "integer",
                            "example": 94,
                            "default": 0
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          }
        },
        "deprecated": false,
        "security": []
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```