Automate 1:1 Coaching Workflows with the Shilo API

Shilo’s 1:1 Coaching feature automatically generates structured coaching periods and per-agent agendas by analyzing the calls your team submits. The Coaching API gives you read-only access to your integration’s coaching settings, the periods that have been generated, and the individual agent agendas within each period—so you can surface coaching prompts, track completion, and build custom reporting workflows.

How 1:1 Coaching Works

At the cadence you configure (weekly, semimonthly, or monthly), Shilo generates a new coaching period covering a window of historical call data. Within each period, Shilo creates an agenda for every eligible agent. Each agenda is a personalized coaching document the agent completes before their 1:1 meeting. After agents submit their agendas, Shilo compiles a team digest the manager can use to prepare.

Coaching Settings

Retrieve your integration’s coaching configuration at any time:

curl https://api.shilo.ai/api/v1/coaching/settings \
  -H "x-api-key: YOUR_API_KEY"

Example response:

{
  "integration_id": "ee6f2136-b94a-4438-9335-3acf5b2a0d31",
  "enabled": true,
  "cadence": "weekly",
  "customization": {
    "focus": "Improve discovery and objection handling",
    "questions": [
      {
        "id": "question-1",
        "order": 0,
        "text": "What should we practice in our next session?"
      }
    ]
  },
  "usage_limits": {
    "integration_limit_seconds": 36000,
    "per_user_limit_seconds": 3600
  }
}

Key Settings Fields

Field	Description
`enabled`	Whether the 1:1 Coaching feature is toggled on for this integration, independent of usage limits
`cadence`	How often coaching periods are generated: `weekly`, `semimonthly`, or `monthly`
`customization.focus`	Optional text describing the current coaching focus area
`customization.questions`	Custom questions added to every agent agenda

Usage Limits

integration_limit_seconds controls the total coaching budget for the entire organization per period, and per_user_limit_seconds controls the budget for each individual agent. Both fields follow the same value convention:

Value	Meaning
`number` (e.g. `3600`)	Maximum coaching seconds allowed
`null`	No limit — coaching is unrestricted
`0`	Coaching is blocked entirely

For example, integration_limit_seconds: 36000 allows up to 10 hours of coaching across all agents per period, while per_user_limit_seconds: 0 blocks coaching for every individual agent regardless of the organization-wide limit.

Coaching Periods

A coaching period represents the time window whose call data was used to generate agendas. Each period has both a data range (period_start to period_end) and a review window (review_period_end) during which agents can submit their agendas.

List Coaching Periods

curl "https://api.shilo.ai/api/v1/coaching/periods?sort=desc&limit=10" \
  -H "x-api-key: YOUR_API_KEY"

Add the optional cadence filter to narrow results:

curl "https://api.shilo.ai/api/v1/coaching/periods?cadence=weekly&sort=desc" \
  -H "x-api-key: YOUR_API_KEY"

Period Status Fields

Field	Values	Description
`review_status`	`open` / `closed`	`open` while agents can still submit agendas (through `review_period_end`); `closed` once the deadline passes
`digest_status`	`pending` / `completed`	`pending` while the team digest is being compiled; `completed` when it is ready

Retrieve a Single Period

curl https://api.shilo.ai/api/v1/coaching/periods/PERIOD_ID \
  -H "x-api-key: YOUR_API_KEY"

The response includes the team digest once digest_status is completed. Use this to surface the manager-facing summary of the period. Example period object:

{
  "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"
}

Agent Agendas

Each agent eligible for a coaching period receives a personalized agenda. The Coaching API returns agenda metadata, generation and completion state, and an authenticated Shilo web deep link when available, so you can direct agents into their coaching session. The endpoints do not return the generated agenda’s questions or body content.

List Agendas for a Period

curl "https://api.shilo.ai/api/v1/coaching/periods/PERIOD_ID/agendas" \
  -H "x-api-key: YOUR_API_KEY"

Filter by a specific user using any supported user identifier:

curl "https://api.shilo.ai/api/v1/coaching/periods/PERIOD_ID/agendas?user_id=external_user_id:agent-123" \
  -H "x-api-key: YOUR_API_KEY"

Retrieve a Single Agenda

curl https://api.shilo.ai/api/v1/coaching/agendas/AGENDA_ID \
  -H "x-api-key: YOUR_API_KEY"

Key Agenda Fields

Field	Description
`agenda_url`	Authenticated Shilo web deep link to the agent’s coaching session. Present only for `ready` agendas with exactly one active user mapping. Requires normal Shilo web authentication; contains no API key or login token
`generation_status`	One of `queued`, `processing`, `ready`, `failed`, or `not_eligible`
`is_completed`	Whether the agent has completed the agenda
`completed_at`	ISO-8601 timestamp of completion, or `null`
`completed_on_time`	Whether the agenda was completed before `review_period_end`, or `null`
`analysis_ready`	Whether the underlying call analysis is ready
`external_user_id`	Your system’s user ID for the agent
`user_id`	Shilo’s internal user UUID

Common Workflows

Check if Coaching is Enabled

curl https://api.shilo.ai/api/v1/coaching/settings \
  -H "x-api-key: YOUR_API_KEY"
# Check: enabled == true AND per_user_limit_seconds != 0 AND integration_limit_seconds != 0

List Open Periods (Agents Can Still Submit)

curl "https://api.shilo.ai/api/v1/coaching/periods?sort=desc&limit=50" \
  -H "x-api-key: YOUR_API_KEY"
# Filter client-side: review_status == "open"

Get All Agendas for an Agent Across a Period

curl "https://api.shilo.ai/api/v1/coaching/periods/PERIOD_ID/agendas?user_id=external_user_id:agent-123" \
  -H "x-api-key: YOUR_API_KEY"

Direct an Agent to Their Agenda

Retrieve the agent’s agenda and send them the agenda_url field when it is present:

curl https://api.shilo.ai/api/v1/coaching/agendas/AGENDA_ID \
  -H "x-api-key: YOUR_API_KEY"
# Use response.agenda_url to link the agent directly to their coaching agenda

The Coaching API is read-only. You cannot create, update, or delete coaching periods or agendas through the API—these are managed automatically by Shilo based on your configured cadence and the calls submitted to your integration.

Get Started

Core Concepts

Guides

Automate 1:1 Coaching Workflows with the Shilo API

How 1:1 Coaching Works

Coaching Settings

Key Settings Fields

Usage Limits

Coaching Periods

List Coaching Periods

Period Status Fields

Retrieve a Single Period

Agent Agendas

List Agendas for a Period

Retrieve a Single Agenda

Key Agenda Fields

Common Workflows

Check if Coaching is Enabled

List Open Periods (Agents Can Still Submit)

Get All Agendas for an Agent Across a Period

Direct an Agent to Their Agenda

​How 1:1 Coaching Works

​Coaching Settings

​Key Settings Fields

​Usage Limits

​Coaching Periods

​List Coaching Periods

​Period Status Fields

​Retrieve a Single Period

​Agent Agendas

​List Agendas for a Period

​Retrieve a Single Agenda

​Key Agenda Fields

​Common Workflows

​Check if Coaching is Enabled

​List Open Periods (Agents Can Still Submit)

​Get All Agendas for an Agent Across a Period

​Direct an Agent to Their Agenda

How 1:1 Coaching Works

Coaching Settings

Key Settings Fields

Usage Limits

Coaching Periods

List Coaching Periods

Period Status Fields

Retrieve a Single Period

Agent Agendas

List Agendas for a Period

Retrieve a Single Agenda

Key Agenda Fields

Common Workflows

Check if Coaching is Enabled

List Open Periods (Agents Can Still Submit)

Get All Agendas for an Agent Across a Period

Direct an Agent to Their Agenda