> ## Documentation Index > Fetch the complete documentation index at: https://docs.siro.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get followups > Retrieve followups with filtering and pagination support. Admins and coaches can access followups for their organization/teams, while regular users can only see their own followups. Returns a paginated list of AI-generated followups tied to recordings. Each followup includes the source recording, rep/team context, score, status, and optional CRM customer data. ## Access Admins and coaches can list followups for their organization and teams. Regular users only see their own followups. ## Pagination Use `limit` (default 25, max 100) and the `cursor` from the previous response to walk pages. The cursor is opaque — pass it back unchanged. ## Common filters | Parameter | Use | | -------------------------------- | ------------------------------------- | | `statuses` | `TO_DO`, `IN_PROGRESS`, or `COMPLETE` | | `minimumScore` | Score floor (1–5, default 3) | | `starred` | Starred followups only | | `createdAfter` / `createdBefore` | ISO 8601 UTC window | | `includeHistory` | Include status changes and notes | | `excludeCrmCustomer` | Omit CRM customer block | ## Related endpoints Followups can also be embedded on a single recording via `showFollowups=true` on [Get recording details](/api-references/get-recording-details). ## OpenAPI ````yaml specs/openapi-internalApi.json get /v1/core/followups openapi: 3.0.0 info: version: 1.0.0 title: Swagger API servers: - url: https://api.siro.ai/ description: Siro API Gateway security: [] externalDocs: description: View the raw OpenAPI Specification in JSON format url: /swagger.json paths: /v1/core/followups: get: summary: Get followups description: >- Retrieve followups with filtering and pagination support. Admins and coaches can access followups for their organization/teams, while regular users can only see their own followups. parameters: - schema: type: string description: Organization id required: false description: Organization id name: organizationId in: query - schema: type: string description: >- Pagination cursor returned by the previous page. Opaque base64-encoded token; do not parse or modify. required: false description: >- Pagination cursor returned by the previous page. Opaque base64-encoded token; do not parse or modify. name: cursor in: query - schema: type: integer minimum: 1 maximum: 100 description: >- Maximum number of followups to return per page (1-100). Default is 25. example: 25 required: false description: >- Maximum number of followups to return per page (1-100). Default is 25. name: limit in: query - schema: type: integer nullable: true default: 3 description: >- Filter by followup score equal to or greater than the minimum score. Can be between 1 and 5. Default is 3. required: false description: >- Filter by followup score equal to or greater than the minimum score. Can be between 1 and 5. Default is 3. name: minimumScore in: query - schema: type: boolean nullable: true description: >- Filter by followup starred state. A followup can be starred via the PATCH /followups/{followupId} endpoint. Default is false. required: false description: >- Filter by followup starred state. A followup can be starred via the PATCH /followups/{followupId} endpoint. Default is false. name: starred in: query - schema: type: array items: type: string enum: - TO_DO - IN_PROGRESS - COMPLETE required: false name: statuses in: query - schema: type: array items: type: integer nullable: true required: false name: scores in: query - schema: type: array items: type: string required: false name: userIds in: query - schema: type: array items: type: string required: false name: teamIds in: query - schema: type: string nullable: true description: >- Only include followups created after this timestamp (ISO 8601, UTC). example: '2024-01-01T00:00:00Z' required: false description: Only include followups created after this timestamp (ISO 8601, UTC). name: createdAfter in: query - schema: type: string nullable: true description: >- Only include followups created before this timestamp (ISO 8601, UTC). example: '2024-01-31T23:59:59Z' required: false description: >- Only include followups created before this timestamp (ISO 8601, UTC). name: createdBefore in: query - schema: type: array items: type: string maxItems: 10 required: false name: conversationTypes in: query - schema: type: boolean nullable: true description: >- Whether to include followuphistory with the followup. Followup history returns all status changes and notes for the followup. Default is false. required: false description: >- Whether to include followuphistory with the followup. Followup history returns all status changes and notes for the followup. Default is false. name: includeHistory in: query - schema: type: boolean nullable: true description: >- Whether to exclude the CRM customer for the followup. Default is false (CRM customer is included). required: false description: >- Whether to exclude the CRM customer for the followup. Default is false (CRM customer is included). name: excludeCrmCustomer in: query responses: '200': description: Get followups content: application/json: schema: type: object properties: data: type: object properties: totalCount: type: number description: Total number of followups in the request query. totalRevenue: type: number description: Total revenue potential in the request query. followups: type: array items: type: object properties: recordingId: type: string description: Followup recording id recordingTitle: type: string nullable: true description: Followup recording title repName: type: string description: Followup rep name repId: type: string description: Followup rep id teamName: type: string nullable: true description: Followup team name teamId: type: string description: Followup team id followupId: type: string description: Followup id dateCreated: type: string description: Followup date created. ISO 8601 UTC timestamp. followupType: type: string enum: - REHASH - CROSS_SELL description: Followup type. Can be REHASH or CROSS_SELL. score: type: number description: Followup score. Can be between 1 and 5. followupAction: type: string nullable: true description: Followup action context: type: array items: type: object properties: header: type: string description: >- Followup context header. Can be MAIN_OBJECTION, EMOTIONAL_TIE, OVERALL_COST, SCOPE, FOLLOW_UP_TIME, SECONDARY_OBJECTION, SCOPE_COST_SUMMARY, OBJECTION_SUMMARY, FOLLOW_UP_SUMMARY, FIRST_PRICE_QUOTE, FINAL_PRICE_QUOTE, PRICING_OPTIONS, FINANCING, COMMITMENT. value: type: string description: Followup context value required: - header - value description: Followup context updatedAt: type: string description: Followup updated at. ISO 8601 UTC timestamp. metadata: type: array items: type: object additionalProperties: type: string description: Followup metadata starred: type: boolean description: Followup starred state. Can be true or false. status: type: string enum: - TO_DO - IN_PROGRESS - COMPLETE description: >- Followup status. Can be TO_DO, IN_PROGRESS, or COMPLETE. thinking: type: string description: Followup thinking and score breakdown history: type: array nullable: true items: type: object properties: id: type: string description: Followup history id updatedBy: type: string description: Followup history updated by updatedByUserId: type: string nullable: true description: >- Followup history updated by user id. Null if the updated by is a Siro system action. createdAt: type: string description: >- Followup history created at. ISO 8601 UTC timestamp. note: type: string description: Followup history note status: type: string enum: - TO_DO - IN_PROGRESS - COMPLETE description: Followup history status required: - id - updatedBy - updatedByUserId - createdAt description: >- Followup history. Returns all status changes and notes for the followup. crmUrl: type: string nullable: true description: >- URL to the customer in the linked CRM (DEPRECATED) crmCustomer: type: object nullable: true properties: id: type: string description: Customer ID name: type: string nullable: true description: Customer name crmUrl: type: string description: URL to this customer in the linked CRM customerType: type: string enum: - ACCOUNT - LEAD - OPPORTUNITY - ENGAGEMENT - CONTACT - DMS_OPPORTUNITY lastActivityAt: type: string nullable: true description: Last activity date createdAt: type: string format: date-time description: Date the Customer record was created in Siro updatedAt: type: string format: date-time description: >- Date the Customer record was last updated in Siro closedAt: type: string nullable: true format: date-time description: >- Date the Customer was closed (applicable to Opportunities) emailAddress: type: string nullable: true description: Customer email addresses phoneNumber: type: string nullable: true description: Customer phone numbers externalId: type: string nullable: true description: Customer external ID amount: type: number nullable: true description: >- Dollar amount associated with a Customer deal disposition: type: string nullable: true description: >- Disposition for the Customer deal: "WON" | "LOST" | "OPEN" recordingId: type: string nullable: true description: >- ID of the most recent recording linked to this customer lastRecordingDate: type: string nullable: true format: date-time description: >- Datetime of the most recent recording linked to this customer numRecordings: type: number nullable: true description: >- Total number of recordings linked to this customer matchingSource: type: string nullable: true enum: - DIRECT - FUZZY - NOT_FOUND description: Source of matching accountId: type: string nullable: true description: Account ID opportunityAccountName: type: string nullable: true description: Account Name associated with the Opportunity contactId: type: string nullable: true description: Contact ID opportunityContactName: type: string nullable: true description: Contact Name associated with the Opportunity opportunityId: type: string nullable: true description: Opportunity ID engagementId: type: string nullable: true description: Engagement ID opportunity: type: object nullable: true properties: id: type: string externalId: type: string description: >- The ID of the opportunity in the external system (e.g. Salesforce) name: type: string nullable: true description: The name of the opportunity amount: type: number description: The dollar amount of the opportunity closedAt: type: string description: The closure date of the opportunity disposition: type: string description: '"WON" | "LOST" | "OPEN"' createdAt: type: string description: The date the opportunity was created updatedAt: type: string description: >- The date the opportunity was last updated recordingId: type: string description: >- The ID of the recording associated to the opportunity accountId: type: string organizationId: type: string account: nullable: true opportunityUsers: type: array items: nullable: true required: - id - externalId - createdAt - updatedAt - organizationId description: Opportunity opportunities: type: object nullable: true properties: data: type: array items: type: object properties: id: type: string externalId: type: string description: >- The ID of the opportunity in the external system (e.g. Salesforce) name: type: string nullable: true description: The name of the opportunity amount: type: number description: The dollar amount of the opportunity closedAt: type: string description: The closure date of the opportunity disposition: type: string description: '"WON" | "LOST" | "OPEN"' createdAt: type: string description: The date the opportunity was created updatedAt: type: string description: >- The date the opportunity was last updated recordingId: type: string description: >- The ID of the recording associated to the opportunity accountId: type: string organizationId: type: string account: nullable: true opportunityUsers: type: array items: nullable: true required: - id - externalId - createdAt - updatedAt - organizationId cursor: type: string nullable: true required: - data description: >- Optional first page of related opportunities for Accounts or Contacts opportunityUsers: type: array nullable: true items: nullable: true description: Users associated with the opportunity contactAccount: type: object nullable: true properties: id: type: string name: type: string nullable: true description: The name of the account externalId: type: string nullable: true description: >- The ID of the account in the external system (e.g. Salesforce) required: - id description: Contact Account address: type: string nullable: true description: Address organizationId: type: string description: Organization ID integrationConnectionId: type: string nullable: true description: Integration Connection ID integrationPlatform: type: string nullable: true enum: - MERGE - SIRO_CUSTOM_INPUT - SERVICE_TITAN - COMPANY_CAM - INGAGE - LEAD_PERFECTION - SPOTIO description: Integration Platform integrationName: type: string nullable: true description: Integration Name required: - id - createdAt - updatedAt - organizationId description: >- Followup CRM customer. Includes the CRM customer if the followup is associated with a CRM customer. hasFollowupComment: type: boolean description: >- Whether the followup has a followup specific comment on the associated recording. note: type: string nullable: true description: >- Followup note. Deprecated in favor of FollowupHistory. completed: type: boolean description: >- Followup completed state. Deprecated in favor of status, which is included in FollowupHistory. completedBy: type: string nullable: true description: >- Followup completed by. Deprecated in favor of FollowupHistory. completedAt: type: string nullable: true description: >- Followup completed at. ISO 8601 UTC timestamp. Deprecated in favor of FollowupHistory. required: - recordingId - recordingTitle - repName - repId - teamName - teamId - followupId - dateCreated - followupType - score - followupAction - context - updatedAt - metadata - starred - status - thinking - crmCustomer - hasFollowupComment - note - completed - completedBy - completedAt description: >- Followups in the request query. Returns up to the limit specified in the request query. required: - totalCount - followups cursor: anyOf: - type: string - type: number - nullable: true pageSize: type: number limit: type: number total: type: number nullable: true hasNextPage: type: boolean required: - data '400': description: Bad Request - Invalid parameters content: application/json: schema: type: object properties: error: type: string description: Error message required: - error '401': description: Unauthorized - User not authenticated content: application/json: schema: type: object properties: error: type: string description: Authentication error message required: - error '403': description: Forbidden - User does not have access content: application/json: schema: type: object properties: error: type: string description: Authorization error message required: - error '404': description: Not Found - Resource not found content: application/json: schema: type: object properties: error: type: string description: Resource not found error message required: - error '422': description: Unprocessable Content - The request failed validation checks content: application/json: schema: type: object properties: issues: type: array items: type: object properties: code: type: string expected: type: string received: type: string path: type: array items: anyOf: - type: string - type: number message: type: string required: - code - path - message name: type: string enum: - ZodError required: - issues - name '500': description: Internal Server Error content: application/json: schema: type: object properties: error: type: string description: Internal server error message required: - error security: - SiroAuthToken: [] components: securitySchemes: SiroAuthToken: type: apiKey in: header name: x-siro-auth-token description: >- OAuth access token for user-scoped requests (Authorization Code or machine-to-machine). Send header `x-siro-auth-token: `. Not an organization API key. x-default: ````