> ## Documentation Index > Fetch the complete documentation index at: https://docs.finterm.ai/llms.txt > Use this file to discover all available pages before exploring further. # A live 0-100 sentiment composite for a ticker: seven components scored vs the ticker's own year, grouped trend / flow / positioning. > Get a live 0-100 sentiment score for a ticker, composed of seven components grouped into trend, flow, and positioning sub-scores. Each component is scored as a percentile vs the ticker’s own trailing year and oriented so 100 is the greed side. The result carries the composite score with a band label (extreme fear to extreme greed; cutoffs versioned in the methodology block), the three sub-scores, every component with its raw value, percentile, and window, deltas over 1, 5, and 20 trading days, a weekly history series, transition flags, and quotable derived[] sentences. A thin option chain degrades to a disclosed coverage with omission reasons, so the score never silently changes meaning. Serves live data only. ## OpenAPI ````yaml /api-reference/openapi-mintlify.json post /api/v1/ticker-sentiment openapi: 3.0.3 info: title: Finterm API version: 1.0.0 description: >- The Finterm financial-data API. Every response is the two-key envelope: `finterm` (the meta header) and `data` (the published result contract), or `finterm` + `error` on failure. ## Error registry | Code | HTTP | Description | Message | | --- | --- | --- | --- | | `INVALID_REQUEST` | 400 | The request body failed schema validation, or the tool rejected the parameters as invalid or incomplete. | The request parameters are invalid or incomplete. | | `INVALID_JSON` | 400 | The request body was not valid JSON. | The request body was not valid JSON. | | `TOKEN_INVALID` | 401 | The bearer token is missing, expired, or not recognized. | The API key is missing, expired, or not recognized. | | `SUBSCRIPTION_REQUIRED` | 402 | An active Finterm Pro subscription is required. The envelope carries the machine-readable error.upgrade_url; after checkout there, retrying succeeds automatically. | An active Finterm Pro subscription is required. | | `RATE_LIMITED` | 429 | The caller has exceeded the request rate limit; retry later. | Too many requests; retry later. | | `RUNTIME_UNAVAILABLE` | 503 | The tool runtime is not available for this deployment. | The service is temporarily unavailable; retry later. | | `RUNTIME_QUEUE_FULL` | 429 | The tool runtime queue is full; retry later. | The service is busy; retry later. | | `RUNTIME_TOOL_UNAVAILABLE` | 501 | The tool is routed but not yet runnable. | This tool is not yet available. | | `RUNTIME_RUN_FAILED` | 502 | The tool runtime reported the run as a non-success terminal state. | The run did not complete successfully. | | `RUNTIME_CONTRACT_MISMATCH` | 502 | The tool runtime returned a result that did not match the published contract. | The service returned an unexpected result shape. | | `TOOL_EXECUTION_FAILED` | 502 | The tool executed but reported an upstream failure. | The tool ran but could not complete the request. | | `UPSTREAM_AUTH` | 502 | A data source rejected the service’s own credentials. A service-side configuration fault, not a caller authentication problem. | A data source could not be accessed due to a service configuration issue. | | `UPSTREAM_QUOTA` | 503 | A data source is over its service-side usage limit; retry later. | A data source is temporarily over capacity; retry later. | | `UPSTREAM_UNAVAILABLE` | 502 | A data source failed, timed out, or returned an unusable response; retry later. | A data source is temporarily unavailable; retry later. | | `BUNDLE_NOT_FOUND` | 404 | No bundle exists with the requested name. | No bundle exists with the requested name. | | `RUN_NOT_FOUND` | 404 | No run exists with the requested id for this caller. | No run exists with the requested id. | | `MANIFEST_NOT_READY` | 409 | The run has not completed, so the sync manifest is not yet available. | The run has not completed yet. | servers: - url: https://api.finterm.ai description: Production security: - bearerAuth: [] tags: - name: Point Tools description: Single-purpose data tools (one request, one synchronous result). - name: Bundle Tools description: Composed multi-section tools served via the run lifecycle. - name: Account description: The authenticated account/entitlement read (works without Pro). - name: Feedback description: Submit bugs, questions, and feature requests (works without Pro). paths: /api/v1/ticker-sentiment: post: tags: - Point Tools summary: >- A live 0-100 sentiment composite for a ticker: seven components scored vs the ticker's own year, grouped trend / flow / positioning. description: >- Get a live 0-100 sentiment score for a ticker, composed of seven components grouped into trend, flow, and positioning sub-scores. Each component is scored as a percentile vs the ticker’s own trailing year and oriented so 100 is the greed side. The result carries the composite score with a band label (extreme fear to extreme greed; cutoffs versioned in the methodology block), the three sub-scores, every component with its raw value, percentile, and window, deltas over 1, 5, and 20 trading days, a weekly history series, transition flags, and quotable derived[] sentences. A thin option chain degrades to a disclosed coverage with omission reasons, so the score never silently changes meaning. Serves live data only. operationId: tickerSentiment requestBody: required: true content: application/json: schema: type: object properties: ticker: type: string description: Stock ticker symbol as_of_date: description: 'As-of date: ''today'' or YYYY-MM-DD' type: string pattern: ^(today|\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]))$ required: - ticker additionalProperties: false responses: '200': description: Success. content: application/json: schema: type: object description: The two-key success envelope. properties: finterm: $ref: '#/components/schemas/FintermMeta' data: $ref: '#/components/schemas/TickerSentiment' required: - finterm - data '400': description: Error (INVALID_REQUEST, INVALID_JSON). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Error (TOKEN_INVALID). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '402': description: Error (SUBSCRIPTION_REQUIRED). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Error (BUNDLE_NOT_FOUND, RUN_NOT_FOUND). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '409': description: Error (MANIFEST_NOT_READY). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Error (RATE_LIMITED, RUNTIME_QUEUE_FULL). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '501': description: Error (RUNTIME_TOOL_UNAVAILABLE). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '502': description: >- Error (RUNTIME_RUN_FAILED, RUNTIME_CONTRACT_MISMATCH, TOOL_EXECUTION_FAILED, UPSTREAM_AUTH, UPSTREAM_UNAVAILABLE). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '503': description: Error (RUNTIME_UNAVAILABLE, UPSTREAM_QUOTA). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' x-codeSamples: - lang: bash label: Live sentiment composite for one symbol. source: finterm tool ticker_sentiment AAPL components: schemas: FintermMeta: type: object description: Canonical result meta header. properties: schema: type: string description: The published result contract id. tool: type: string description: The snake_case tool id. args: type: object additionalProperties: true description: The arguments the caller requested. request_id: type: string description: Server-set, ephemeral request id. cursor: type: string description: Opaque pagination cursor (feed tools only). required: - schema - tool - args TickerSentiment: type: object properties: ticker: type: string as_of_date: type: string price: nullable: true type: number score: nullable: true type: number band: nullable: true type: string enum: - extreme fear - fear - neutral - greed - extreme greed coverage: type: string sub_scores: type: object properties: trend: nullable: true type: number flow: nullable: true type: number positioning: nullable: true type: number required: - trend - flow - positioning additionalProperties: false components: type: array items: type: object properties: id: type: string group: type: string enum: - trend - flow - positioning raw: type: number unit: type: string enum: - pct - ratio - share_pct - rank - days percentile: type: number score: type: number window: type: string note: type: string required: - id - group - raw - unit - percentile - score - window additionalProperties: false omitted: type: array items: type: object properties: component: type: string reason: type: string enum: - history_accumulating - thin_chain - insufficient_history - no_data required: - component - reason additionalProperties: false delta: type: object properties: d1: nullable: true type: number d5: nullable: true type: number d20: nullable: true type: number required: - d1 - d5 - d20 additionalProperties: false history: type: array items: type: object properties: date: type: string score: type: number coverage: type: string required: - date - score - coverage additionalProperties: false flags: type: array items: type: string context: type: object properties: next_earnings: nullable: true type: object properties: date: type: string days: type: number confirmed: type: boolean required: - date - days - confirmed additionalProperties: false required: - next_earnings additionalProperties: false derived: type: array items: type: string scope: type: object properties: selection: type: string enum: - full_chain - partial_chain contracts_analyzed: type: number expirations_covered: type: number pages_fetched: type: number required: - selection - contracts_analyzed - expirations_covered - pages_fetched additionalProperties: false data_quality: type: object properties: status: type: string enum: - ok - degraded - no_data history: type: object properties: status: type: string enum: - ok - accumulating days_collected: type: number required: - status - days_collected additionalProperties: false note: type: string required: - status - history additionalProperties: false methodology: type: object properties: version: type: string component_scoring: type: string composite: type: string band_cutoffs: type: array items: anyOf: - type: number - type: number - type: number - type: number minItems: 4 maxItems: 4 orientation: type: string flow_sharing: type: string required: - version - component_scoring - composite - band_cutoffs - orientation - flow_sharing additionalProperties: false required: - ticker - as_of_date - price - score - band - coverage - sub_scores - components - omitted - delta - history - flags - context - derived - scope - data_quality - methodology additionalProperties: false ErrorEnvelope: type: object description: The two-key error envelope. properties: finterm: $ref: '#/components/schemas/FintermMeta' error: type: object properties: code: type: string description: Stable public error code. message: type: string description: Human-readable, external-clean message. upgrade_url: type: string description: >- Machine-readable upgrade URL, present only on SUBSCRIPTION_REQUIRED (402): complete checkout there, then retry; access activates automatically. required: - code - message required: - finterm - error securitySchemes: bearerAuth: type: http scheme: bearer description: A live account API key from `FINTERM_API_KEY`. ````