> ## 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 Agent Coaching Agendas for a Period — Shilo

> List all agent coaching agendas for a period, including ready, failed, and not-eligible agendas. Filter by user ID to find a specific agent's agenda.

Use this endpoint to retrieve metadata for all coaching agendas associated with a specific coaching period. Each item includes the agenda's generation and completion state and, when available, an authenticated Shilo web deep link. This endpoint does not return the generated agendas' questions or body content. Results include agendas of all statuses, including those still queued or processing, those that failed generation, and agents who were not eligible during that period.

## Endpoint

```text theme={null}
GET https://api.shilo.ai/api/v1/coaching/periods/{periodId}/agendas
```

## Authentication

Include your API key in the request header:

```text theme={null}
x-api-key: YOUR_API_KEY
```

## Path Parameters

<ParamField path="periodId" type="string" required>
  The unique identifier of the coaching period whose agendas you want to list. Obtain period IDs from the [List Periods](/api-reference/coaching/list-periods) endpoint.
</ParamField>

## Query Parameters

<ParamField query="limit" default="50" type="number">
  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" default="desc" type="string">
  Sort order by agenda creation date. Accepted values: `asc`, `desc`.
</ParamField>

<ParamField query="user_id" type="string">
  Filter results to a specific agent's agenda. Accepted formats:

  * `id:{uuid}` — prefixed Shilo UUID
  * `external_user_id:{string}` — your system's user ID
  * `{uuid}` — bare Shilo UUID
</ParamField>

## Response

### 200 — Success

Returns a `CoachingAgendasResponseDto` object containing a `data` array of `CoachingAgenda` objects and a `pagination` block.

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

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

    <ResponseField name="period_id" type="string">
      The coaching period this agenda belongs to.
    </ResponseField>

    <ResponseField name="integration_id" type="string">
      Your Shilo integration identifier.
    </ResponseField>

    <ResponseField name="user_id" type="string | null">
      Shilo user ID of the agent this agenda was generated for. May be `null` if the user record was removed.
    </ResponseField>

    <ResponseField name="external_user_id" type="string">
      Your system's user ID for the agent.
    </ResponseField>

    <ResponseField name="title" type="string | null">
      Human-readable title for the agenda (e.g. `"June coaching"`). May be `null` if not yet generated.
    </ResponseField>

    <ResponseField name="cadence" type="string">
      Cadence of the parent period: `weekly`, `semimonthly`, or `monthly`.
    </ResponseField>

    <ResponseField name="period_start" type="string">
      ISO-8601 date marking the start of the parent coaching period.
    </ResponseField>

    <ResponseField name="period_end" type="string">
      ISO-8601 date marking the end of the parent coaching period.
    </ResponseField>

    <ResponseField name="review_period_end" type="string">
      ISO-8601 date marking the end of the review window during which the agent can submit the agenda.
    </ResponseField>

    <ResponseField name="generation_status" type="string">
      Generation status of the agenda. One of `queued`, `processing`, `ready`, `failed`, or `not_eligible`.
    </ResponseField>

    <ResponseField name="is_completed" type="boolean">
      Whether the agent has completed the agenda.
    </ResponseField>

    <ResponseField name="completed_at" type="string | null">
      ISO-8601 timestamp of when the agent completed the agenda. `null` if not completed.
    </ResponseField>

    <ResponseField name="completed_on_time" type="boolean | null">
      Whether the agenda was completed before `review_period_end`. `null` if not completed.
    </ResponseField>

    <ResponseField name="analysis_ready" type="boolean">
      Whether post-submission analysis has produced a stored summary.
    </ResponseField>

    <ResponseField name="agenda_url" type="string | null">
      Authenticated Shilo web deep link the agent can use to open their coaching session. Present only for `ready` agendas with exactly one active user mapping. Requires normal Shilo web authentication and does not contain an API key or login token. `null` otherwise.
    </ResponseField>

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

    <ResponseField name="updated_date" type="string">
      ISO-8601 timestamp of the most recent update to this agenda.
    </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 for the next page. `null` when `has_more` is `false`.
    </ResponseField>
  </Expandable>
</ResponseField>

### 400 — Bad Request

The `periodId` path parameter or one or more query parameters contain invalid values.

### 401 — Unauthorized

Your API key is missing or invalid.

### 404 — Not Found

No coaching period with the given `periodId` exists in your organization.

## Example Request

```bash theme={null}
curl --request GET \
  --url "https://api.shilo.ai/api/v1/coaching/periods/ee6f2136-b94a-4438-9335-3acf5b2a0d31/agendas?limit=50&sort=desc" \
  --header "x-api-key: YOUR_API_KEY"
```

## Example Response

```json theme={null}
{
  "data": [
    {
      "id": "c1a2b3d4-e5f6-7890-abcd-ef1234567890",
      "period_id": "ee6f2136-b94a-4438-9335-3acf5b2a0d31",
      "integration_id": "a3c9e214-1f2b-4d78-bb01-7e5f9c3d0a12",
      "user_id": "f7e6d5c4-b3a2-1098-fedc-ba9876543210",
      "external_user_id": "usr_abc123",
      "title": "June coaching",
      "cadence": "weekly",
      "period_start": "2026-06-01",
      "period_end": "2026-06-07",
      "review_period_end": "2026-06-14",
      "generation_status": "ready",
      "is_completed": false,
      "completed_at": null,
      "completed_on_time": null,
      "analysis_ready": true,
      "agenda_url": "https://app.shilo.ai/i/a3c9e214-1f2b-4d78-bb01-7e5f9c3d0a12/insights/agent/usr_abc123/coaching/c1a2b3d4-e5f6-7890-abcd-ef1234567890?itemType=coaching",
      "created_date": "2026-06-08T13:00:00Z",
      "updated_date": "2026-06-08T13:00:00Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}
```

<Note>
  This endpoint returns agendas of all statuses: `queued`, `processing`, `ready`, `failed`, and `not_eligible`. Filter on the `generation_status` field in your application to show only relevant records to managers or agents.
</Note>