> Finks API docs. Every page: https://finks.ai/llms.txt. The OpenAPI spec: https://finks.ai/docs/openapi.json.

# Screener

Find the companies that match your criteria.

Base URL: https://data.finks.ai. Send your key as `Authorization: Bearer $FINKS_API_KEY`.

## Screen companies

`POST /v1/screener` (#post-v1-screener)

Companies that pass your filters, ranked by any field.

- Read GET /v1/screener/fields first: it lists every field's name, type, allowed values and operators.
- `operation`: `rank` orders the matches by `ranking`; `filter` returns them by symbol. `subject`: `{ "subject_type": "company" }`.
- `predicates`: each a `field`, an `operator` (`eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `between`, `in`, `not_in`) and a `value`: a number, text or true/false, a list for `in` and `not_in`, or `{ "lower", "upper" }` for `between`.
- `ranking`: a list of `{ "field", "direction" }`, `asc` or `desc`. `requested_fields`: what each row returns. `limit`: rows per page, up to your plan's page cap.

### Parameters

- `view` (string, query, can be null)

### Request body

- `natural_language` (string, can be null): The screen in words (beta). `interpretation` says how it was read.
- `query` (object, can be null): The screen. Send this or `natural_language`.

### Response

- `coverage` (object, required): How many companies were evaluated and matched.
- `data` (array of object, required): One row per company: `fields` maps each requested field to its `value`, with `as_of` and `basis` (`daily`, `ttm`, `fy`).
- `normalized_query` (object, required)
- `query_id` (string, required): Identity of this immutable run.
- `query_version` (integer, required)
- `usage` (object, required)
- `interpretation` (object, can be null)
- `next_cursor` (string, can be null): Send it as `query.cursor`, with the rest of the query unchanged, for the next page. Absent on the last page.
- `total_count` (integer, can be null)

### Statuses

- 200: One page of the screen, ordered by the ranking (or symbol), with coverage. A screen matching nothing is a 200 with empty `data`. A `natural_language` screen, or one leaving a default implicit, also carries `interpretation` (`defaults_applied`); `normalized_query` states every default and reruns the screen without a model. Under `view=compact`, a `CompactScreenerPage` (`results[]`), each row's `as_of` naming the values dated differently from the page.
- 400: `request.invalid` naming the body field or the query parameter (`view`), `request.out_of_plan` naming the allowance (`query.limit` above the plan's screener cap: `screener_search`'s `page_cap`, Free 10 / Starter 50 / Pro 100 / Scale 100; `query.limit` above 100 is `request.invalid`), `invalid_filter`, `unsupported_subject`, `unsupported_field_for_subject` naming the field, `unresolvable_query` (an `as_of` other than the current snapshot, or `natural_language` that maps to nothing: `reason: nothing_mapped`), `invalid_cursor`, or `cursor_expired` (the snapshot was rebuilt)
- 401: Missing, unknown, revoked, or expired key
- 413: `request.too_large`, the body is over the 2 MB limit
- 429: Rate limited, quota denied, or spend cap reached
- 501: `natural_language` from an account it is not enabled for, an operation other than `filter` or `rank`, or the plan grants no serving limit
- 503: `content.unresolved`, the screen could not be read, or `natural_language` could not be compiled (`reason: compile`)

### Request

```bash
curl -sS "https://data.finks.ai/v1/screener" \
  -H "Authorization: Bearer $FINKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": {
    "operation": "rank",
    "subject": {
      "subject_type": "company"
    },
    "predicates": [
      {
        "field": "sector",
        "operator": "eq",
        "value": "Technology"
      },
      {
        "field": "ttm_price_to_earnings_ratio",
        "operator": "between",
        "value": {
          "lower": 0,
          "upper": 25
        }
      }
    ],
    "ranking": [
      {
        "field": "market_cap",
        "direction": "desc"
      }
    ],
    "requested_fields": [
      "industry",
      "market_cap",
      "price",
      "revenue",
      "ttm_net_profit_margin",
      "sector",
      "ttm_price_to_earnings_ratio"
    ],
    "limit": 10
  }
}'
```

Metered: one `screener_search` per screen, 10 credits on every plan.

- Data: US company screener, from Finks. Updates: daily, current snapshot.

## Screener fields

`GET /v1/screener/fields` (#get-v1-screener-fields)

Every field you can filter, rank or return.

### Response

- `fields` (array of object, required)
- `as_of` (string, can be null)

### Statuses

- 200: Every screener field: type, unit, operators, basis, live enum values for text fields, freshness source, rights, and whether it is servable today
- 401: Missing, unknown, revoked, or expired key

### Request

```bash
curl -sS "https://data.finks.ai/v1/screener/fields" \
  -H "Authorization: Bearer $FINKS_API_KEY"
```

Not metered.

- Data: US company screener, from Finks. Updates: daily, current snapshot.