Audio Recaps

List a user's progress across audio recaps

GET · Audio Recaps

Returns recap-level progress for one user on each requested audio recap component: completion, approximate length, listened and remaining seconds. Pass componentIds (public component ids or component Mongo _ids, up to 100) as a comma-separated list or repeated parameter. When componentIds is omitted, every recap the user has progress on is returned. Ids that are not audio recap components in this organization are listed in notFound.

OpenAPI specification

GET/api/v1/audio-recaps/users/{userId}/progress

Authentication

x-api-key

Request

curl --globoff --request GET \
  --url 'https://api.example.com/api/v1/audio-recaps/users/%3CuserId%3E/progress' \
  --header 'x-api-key: <API_KEY>'

Replace credential and <field> placeholders with your own values. URL placeholders appear as %3Cfield%3E. Review the example values before sending your request.

Replace https://api.example.com with the API server URL.

Parameters

userIdpath · string · required

Embed-token userId

componentIdsquery · array

Audio recap component ids (max 100). Omit to return every recap the user has started.

Responses

200

{
  "type": "object",
  "properties": {
    "userId": {
      "type": "string"
    },
    "recaps": {
      "description": "One entry per resolved component, in request order.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "componentId": {
            "type": "string",
            "description": "Public component id (audio_recap_…)."
          },
          "generationStatus": {
            "type": "string",
            "enum": [
              "pending",
              "completed",
              "failed"
            ],
            "description": "Script generation for the recap."
          },
          "completionPct": {
            "type": "number",
            "description": "sectionsCompleted / totalSections, 0–100."
          },
          "totalSections": {
            "type": "number",
            "description": "Number of sections in the recap."
          },
          "sectionsCompleted": {
            "type": "number",
            "description": "Sections this user has completed."
          },
          "durationSeconds": {
            "type": "number",
            "description": "Approximate length of the recap in seconds. Uses the generated audio length per section, or an estimate from the script while audio is not ready."
          },
          "listenedSeconds": {
            "type": "number",
            "description": "Approximate seconds the user has listened to."
          },
          "remainingSeconds": {
            "type": "number",
            "description": "durationSeconds - listenedSeconds."
          },
          "lastActivityAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Most recent progress update from this user. Null if the user has not started."
          }
        },
        "required": [
          "componentId",
          "generationStatus",
          "completionPct",
          "totalSections",
          "sectionsCompleted",
          "durationSeconds",
          "listenedSeconds",
          "remainingSeconds",
          "lastActivityAt"
        ]
      }
    },
    "notFound": {
      "description": "Requested ids that are not audio recap components in this organization.",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "userId",
    "recaps",
    "notFound"
  ]
}

400More than 100 componentIds