> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finscreener.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Screener

> Execute a saved screener and get matching results

Execute a previously saved screener query and return the matching companies or GST records.

<Note>
  This endpoint runs the saved FQL query in real-time against the latest data. Results are not cached — you always get fresh data.
</Note>

## Path Parameters

<ParamField path="screener_id" type="string" required>
  The ID of the saved screener to execute
</ParamField>

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token: `Bearer <access_token>`
</ParamField>

## Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number for pagination
</ParamField>

<ParamField query="limit" type="integer" default="10">
  Number of results per page (max 100)
</ParamField>

## Response

<ResponseField name="data" type="array">
  Array of matching company or GST records
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of matching records
</ResponseField>

<ResponseField name="page" type="integer">
  Current page number
</ResponseField>

<ResponseField name="limit" type="integer">
  Results per page
</ResponseField>

<ResponseField name="screener" type="object">
  Screener metadata (id, name, type, query)
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.finscreener.in/api/screener/screeners/scr_123/run?page=1&limit=10" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.finscreener.in/api/screener/screeners/scr_123/run",
      params={"page": 1, "limit": 10},
      headers={"Authorization": f"Bearer {token}"}
  )
  results = response.json()
  print(f"Found {results['total']} matching records")
  for record in results["data"]:
      print(record)
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.finscreener.in/api/screener/screeners/scr_123/run?page=1&limit=10',
    {
      method: 'POST',
      headers: { Authorization: `Bearer ${token}` }
    }
  );
  const results = await response.json();
  console.log(`Found ${results.total} matching records`);
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "data": [
      {
        "CIN": "L17110MH1973PLC019786",
        "company": "RELIANCE INDUSTRIES LIMITED",
        "City": "Mumbai",
        "State": "Maharashtra",
        "paidUpCapital": 6765800000,
        "llpStatus": "Active"
      },
      {
        "CIN": "L65910MH2007PLC169487",
        "company": "RELIANCE JIO INFOCOMM LIMITED",
        "City": "Mumbai",
        "State": "Maharashtra",
        "paidUpCapital": 4500000000,
        "llpStatus": "Active"
      }
    ],
    "total": 45,
    "page": 1,
    "limit": 10,
    "screener": {
      "id": "scr_123",
      "name": "Mumbai IT Companies",
      "type": "company",
      "query": "City == 'Mumbai' AND NICCode IN [62011, 62012]"
    }
  }
  ```

  ```json Screener Not Found theme={null}
  {
    "detail": "Screener not found"
  }
  ```
</ResponseExample>

## Error Codes

| Status | Description                                        |
| ------ | -------------------------------------------------- |
| 200    | Screener executed successfully                     |
| 401    | Unauthorized — invalid or expired token            |
| 404    | Screener not found or doesn't belong to user       |
| 422    | Invalid query — FQL syntax error in saved screener |
| 429    | Rate limit exceeded                                |

<Tip>
  Use **Run Screener** to build automated pipelines. Save a screener once, then run it on a schedule to track changes in matching records over time.
</Tip>