> ## Documentation Index > Fetch the complete documentation index at: https://docs.upriver.ai/llms.txt > Use this file to discover all available pages before exploring further. # Search the radar by natural language (Beta) ## OpenAPI ````yaml /api-reference/openapi.json post /v2/radar/search openapi: 3.1.0 info: title: Upriver API description: >- A social insights API for ad generation platforms. It provides structured signals, like psychographics, behavioral insights, trends, and audience language, to help AI models generate relevant, higher-converting ads. version: 1.0.0 servers: - url: https://api.upriver.ai description: Production API server security: [] tags: - name: Brands - name: Products - name: Creators - name: Audience - name: Sponsorships - name: Trends - name: Trends Radar (Beta) - name: Breakout Topics - name: Taxonomy paths: /v2/radar/search: post: tags: - Trends Radar (Beta) summary: Search the radar by natural language (Beta) operationId: search_radar_beta requestBody: content: application/json: schema: $ref: '#/components/schemas/RadarSearchInput' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/RadarSearchResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: RadarSearchInput: properties: query: type: string maxLength: 500 minLength: 2 title: Query description: Natural-language description of the trend, topic, or audience. limit: type: integer maximum: 50 minimum: 1 title: Limit default: 10 card_type: anyOf: - type: string enum: - trend_moment - topic - entity_breakout - type: 'null' title: Card Type description: Restrict results to one item type. program: type: string const: general_market title: Program description: Production market catalog searched for results. default: general_market lifecycle: anyOf: - type: string - type: 'null' title: Lifecycle description: Restrict results to one lifecycle state. brand_safety: anyOf: - type: string - type: 'null' title: Brand Safety description: Restrict results by brand-safety assessment. type: object required: - query title: RadarSearchInput RadarSearchResponse: properties: beta: type: string title: Beta description: Beta status caveat. default: >- Beta: response shapes may change and this surface may converge with /v2/trends. results: items: $ref: '#/components/schemas/RadarSearchResult' type: array title: Results type: object required: - results title: RadarSearchResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError RadarSearchResult: properties: item: $ref: '#/components/schemas/RadarItem' match_score: type: number title: Match Score description: Semantic match strength for the query. type: object required: - item - match_score title: RadarSearchResult ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError RadarItem: properties: id: type: string title: Id description: Stable item identifier. type: type: string enum: - trend_moment - topic - entity_breakout title: Type description: >- trend_moment: a participatory trend moment. topic: a durable subject area. entity_breakout: a product or brand gaining attention. name: type: string title: Name description: Human-readable card title. description: anyOf: - type: string - type: 'null' title: Description description: One-sentence summary of what the card covers. insight: anyOf: - type: string - type: 'null' title: Insight description: Analyst note on what is driving this right now. how_to_act: anyOf: - type: string - type: 'null' title: How To Act description: Suggested content, product, or campaign activation angle. brand_safety: anyOf: - type: string - type: 'null' title: Brand Safety description: 'Brand-safety assessment: safe, caution, unsafe.' lifecycle_state: anyOf: - type: string - type: 'null' title: Lifecycle State description: >- Where the card sits in its lifecycle: emerging, rising, peaking, steady, or declining. momentum_ratio: anyOf: - type: number - type: 'null' title: Momentum Ratio description: Recent activity relative to the card's own baseline. value_score: anyOf: - type: number - type: 'null' title: Value Score description: Composite quality/opportunity score. stats: anyOf: - additionalProperties: true type: object - type: 'null' title: Stats description: >- Live evaluation stats: video and creator counts, freshness, audience and format composition, publishing activity, and the collection scope in which supporting videos were observed. Optional presentation_formats list caption-based format names and their evidence_basis: caption_label, caption_description, or mixed. Optional examples list sample videos with tiktok_id, url, caption, creator, views, published_at, and cover_url: a temporary image URL to load directly, or null when no image is available. personas: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' title: Personas description: Audience personas this card serves, with strength. program: anyOf: - type: string - type: 'null' title: Program description: Market catalog this item belongs to. first_seen: anyOf: - type: string format: date-time - type: 'null' title: First Seen description: When this item first appeared on the radar. last_updated: anyOf: - type: string format: date-time - type: 'null' title: Last Updated description: When this item's stats were last refreshed. archived: type: boolean title: Archived description: >- True when the item is no longer tracked; archived items are excluded from lists and search. default: false type: object required: - id - type - name title: RadarItem description: 'One card: a named slice of cultural activity with its live stats.' securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.