> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shilo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List All 1:1 Coaching Periods — Shilo Coaching API

> Retrieve a paginated list of 1:1 coaching periods for your integration. Filter by cadence. Each period shows its review status and digest readiness.

Use this endpoint to retrieve the list of coaching periods generated for your Shilo integration. Each period represents a discrete time window during which call data is collected for agent coaching agendas. You can use this endpoint to discover active and past periods, check whether the review window is still open, and determine whether the team digest has been generated yet.

## Endpoint

```
GET https://api.shilo.ai/api/v1/coaching/periods
```

## Authentication

Include your API key in the request header:

```
x-api-key: YOUR_API_KEY
```

## Query Parameters

<ParamField query="limit" type="number" default="50">
  Maximum number of results to return per page. Maximum value is `100`.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor from a previous response's `pagination.next_cursor`. Omit to start from the beginning.
</ParamField>

<ParamField query="sort" type="string" default="desc">
  Sort order by created date. Accepted values: `asc`, `desc`. Defaults to `desc` so the most recent period appears first.
</ParamField>

<ParamField query="cadence" type="string">
  Filter results to a specific coaching cadence. Accepted values: `monthly`, `semimonthly`, `weekly`. Omit to return periods of all cadences.
</ParamField>

## Response

### 200 — Success

Returns a `CoachingPeriodsResponseDto` containing a `data` array of coaching period objects and a `pagination` block.

<ResponseField name="data" type="array">
  Array of coaching period objects.

  <Expandable title="CoachingPeriod object">
    <ResponseField name="id" type="string">
      Unique identifier for the coaching period (UUID).
    </ResponseField>

    <ResponseField name="cadence" type="string">
      The cadence for this period: `weekly`, `semimonthly`, or `monthly`.
    </ResponseField>

    <ResponseField name="period_start" type="string">
      Calendar date on which call data collection for this period begins (inclusive). Format: `YYYY-MM-DD`.
    </ResponseField>

    <ResponseField name="period_end" type="string">
      Calendar date on which call data collection for this period ends (inclusive). Format: `YYYY-MM-DD`.
    </ResponseField>

    <ResponseField name="review_period_end" type="string">
      Inclusive UTC calendar-date deadline for agents to complete their coaching agendas. Format: `YYYY-MM-DD`.
    </ResponseField>

    <ResponseField name="review_status" type="string">
      Whether the review window is currently open. `open` through the end of `review_period_end` in UTC; `closed` thereafter.
    </ResponseField>

    <ResponseField name="digest_status" type="string">
      Processing status of the team-level digest for this period. `pending` while the digest is being generated; `completed` when the digest is available on the period detail.
    </ResponseField>

    <ResponseField name="created_date" type="string">
      ISO-8601 timestamp of when the period record was created.
    </ResponseField>

    <ResponseField name="updated_date" type="string">
      ISO-8601 timestamp of the most recent update to this period record.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata.

  <Expandable title="pagination object">
    <ResponseField name="has_more" type="boolean">
      Whether additional pages of results exist.
    </ResponseField>

    <ResponseField name="next_cursor" type="string | null">
      Cursor to pass as the `cursor` query parameter for the next page. `null` when `has_more` is `false`.
    </ResponseField>
  </Expandable>
</ResponseField>

### 400 — Bad Request

One or more query parameters contain invalid values.

### 401 — Unauthorized

Your API key is missing or invalid.

## Example Request

```bash theme={null}
curl --request GET \
  --url "https://api.shilo.ai/api/v1/coaching/periods?limit=10&sort=desc&cadence=weekly" \
  --header "x-api-key: YOUR_API_KEY"
```

## Example Response

```json theme={null}
{
  "data": [
    {
      "id": "ee6f2136-b94a-4438-9335-3acf5b2a0d31",
      "cadence": "weekly",
      "period_start": "2026-06-01",
      "period_end": "2026-06-07",
      "review_period_end": "2026-06-14",
      "review_status": "open",
      "digest_status": "pending",
      "created_date": "2026-06-08T12:34:56Z",
      "updated_date": "2026-06-08T12:34:56Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}
```

<Note>
  `review_status` is `open` through the end of `review_period_end` in UTC, and transitions to `closed` after that deadline passes. Use this field to determine whether agents can still submit their agendas for the period.
</Note>