> ## Documentation Index > Fetch the complete documentation index at: https://docs.video2ctx.dev/llms.txt > Use this file to discover all available pages before exploring further. # Calculate public trend signals for a topic > Builds a diversified topic sample, persists public metric snapshots, calculates observed acceleration when history exists, and optionally adds GLM-generated evidence-grounded themes and content gaps. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/providers/{provider}/trends openapi: 3.1.0 info: title: video2ctx API version: 1.0.0 license: name: Apache License 2.0 identifier: Apache-2.0 description: >- Consumer-facing contract for the hosted video2ctx API. First-party application and operator routes are documented separately at https://docs.video2ctx.dev/internals/overview. servers: - url: https://api.video2ctx.dev description: Hosted video2ctx API security: [] tags: - name: System description: Service status and machine-readable documentation. - name: Providers description: Supported external video providers and their capabilities. - name: Discovery description: Search, browse, and trend research. - name: Videos description: Video metadata and evidence. - name: Channels description: Channel inspection. - name: Playlists description: Playlist inspection. - name: Projects description: Private research projects and saved material. - name: Research description: Imports, jobs, cited answers, comparisons, and reports. - name: Exports description: Project export creation and download. - name: Monitoring description: Monitors, notifications, and digest preferences. - name: Billing description: Checkout, usage, and Stripe webhook handling. paths: /v1/providers/{provider}/trends: get: tags: - Discovery summary: Calculate public trend signals for a topic description: >- Builds a diversified topic sample, persists public metric snapshots, calculates observed acceleration when history exists, and optionally adds GLM-generated evidence-grounded themes and content gaps. operationId: researchTrends parameters: - name: provider in: path required: true description: External video provider. schema: type: string enum: - youtube example: youtube - name: q in: query required: true description: Topic to research. schema: type: string maxLength: 200 example: AI agents - name: limit in: query required: false description: Number of diversified videos to enrich; clamped to 8–30. schema: type: integer minimum: 8 maximum: 30 default: 20 - name: insights in: query required: false description: AI insight mode. Use deterministic to skip GLM analysis. schema: type: string enum: - ai - deterministic default: ai responses: '200': description: Topic trend report. content: application/json: schema: $ref: '#/components/schemas/TrendReport' headers: X-Credits-Charged: $ref: '#/components/headers/CreditsCharged' X-Credits-Remaining: $ref: '#/components/headers/CreditsRemaining' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/InsufficientCredits' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/ServiceUnavailable' security: - bearerApiKey: [] - sessionCookie: [] - apiKey: [] - demoUser: [] components: schemas: TrendReport: type: object required: - provider - query - generatedAt - sampleSize - methodologyVersion - methodology - sample - confidence - summary - videos - hashtags - titlePatterns - durationMix - plan - warnings properties: provider: type: string enum: - youtube query: type: string generatedAt: type: string format: date-time sampleSize: type: integer minimum: 0 methodologyVersion: const: '2.0' methodology: type: string sample: type: object required: - candidateVideos - enrichedVideos - channels - observedVideos properties: candidateVideos: type: integer minimum: 0 enrichedVideos: type: integer minimum: 0 channels: type: integer minimum: 0 observedVideos: type: integer minimum: 0 confidence: type: object required: - score - level - reasons properties: score: type: integer minimum: 0 maximum: 100 level: type: string enum: - low - medium - high reasons: type: array items: type: string summary: type: object required: - totalViews - medianViewsPerHour - publishedLast7Days - breakoutCount - acceleratingCount properties: totalViews: type: integer minimum: 0 medianViewsPerHour: type: number minimum: 0 publishedLast7Days: type: integer minimum: 0 breakoutCount: type: integer minimum: 0 acceleratingCount: type: integer minimum: 0 medianObservedViewsPerHour: type: number minimum: 0 videos: type: array items: $ref: '#/components/schemas/TrendVideo' hashtags: type: array items: type: object additionalProperties: true titlePatterns: type: array items: type: object additionalProperties: true durationMix: type: array items: type: object additionalProperties: true insights: type: object description: >- Optional GLM-generated analysis. Omitted when deterministic mode is requested or model inference fails. additionalProperties: true plan: type: object additionalProperties: true warnings: type: array items: type: string TrendVideo: type: object required: - id - title - channel - thumbnails - description - viewCount - signalSource - confidenceScore - hashtags - keywords - trendScore - trendBand - url properties: id: type: string title: type: string channel: type: object required: - id - name properties: id: type: string name: type: string thumbnails: type: array items: $ref: '#/components/schemas/Thumbnail' description: type: string durationSeconds: type: integer minimum: 0 publishedTimeText: type: string publishDate: type: string ageHours: type: number minimum: 0 viewCount: type: integer minimum: 0 viewsPerHour: type: number minimum: 0 observedViewsPerHour: type: number minimum: 0 previousViewsPerHour: type: number minimum: 0 accelerationPercent: type: number observationHours: type: number minimum: 0 viewDelta: type: integer minimum: 0 likeDelta: type: integer minimum: 0 commentDelta: type: integer minimum: 0 commentCount: type: integer minimum: 0 likeCount: type: integer minimum: 0 engagementRate: type: number minimum: 0 channelBaselineViewsPerHour: type: number minimum: 0 channelLift: type: number minimum: 0 searchRank: type: integer minimum: 1 signalSource: type: string enum: - observed - estimated confidenceScore: type: integer minimum: 0 maximum: 100 hashtags: type: array items: type: string keywords: type: array items: type: string trendScore: type: integer minimum: 0 maximum: 100 trendBand: type: string enum: - Breakout - Rising - Steady url: type: string format: uri Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string example: QUERY_REQUIRED message: type: string details: {} requestId: type: string Thumbnail: type: object required: - url properties: url: type: string format: uri width: type: integer minimum: 0 height: type: integer minimum: 0 headers: CreditsCharged: description: Credits settled for this operation. schema: type: integer minimum: 0 CreditsRemaining: description: Current balance in the owning user account after the request is metered. schema: type: integer responses: Unauthorized: description: Authentication is required. content: application/json: schema: $ref: '#/components/schemas/Error' InsufficientCredits: description: >- The user account does not have enough credits. Error code: INSUFFICIENT_CREDITS. content: application/json: schema: $ref: '#/components/schemas/Error' headers: X-Credits-Charged: $ref: '#/components/headers/CreditsCharged' X-Credits-Remaining: $ref: '#/components/headers/CreditsRemaining' Forbidden: description: The caller is not allowed to perform this operation. content: application/json: schema: $ref: '#/components/schemas/Error' ValidationError: description: The request failed validation. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: The public rate limit was exceeded. content: application/json: schema: $ref: '#/components/schemas/Error' ServerError: description: An unexpected server error occurred. content: application/json: schema: $ref: '#/components/schemas/Error' ServiceUnavailable: description: An upstream AI or YouTube service is unavailable. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerApiKey: type: http scheme: bearer bearerFormat: API key description: >- Permanent personal API key created in the dashboard. Example: curl -H "Authorization: Bearer aty_…" https://your-host/v1/projects sessionCookie: type: apiKey in: cookie name: better-auth.session_token description: >- Better Auth session cookie. A production deployment may use the secure-prefixed cookie name; same-origin browser requests send it automatically. apiKey: type: apiKey in: header name: X-API-Key description: >- Legacy-compatible header for a permanent personal API key. Prefer Authorization: Bearer aty_…. demoUser: type: apiKey in: header name: X-Demo-User description: >- Local development only. Any stable value selects an isolated demo account. Rejected in production. ````