> ## 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.

# Access & Entitlements

> What this API key is allowed to do

The authoritative description of what your API key may do. Call it once at integration
time (and periodically afterwards) to self-configure: it states, per dataset, whether
access is granted and by what, the exact territory and the exact date window that will
be applied to every query, plus your rate limits and credit balances.

<Note>
  The data endpoints enforce **exactly** what this endpoint reports. If a result set is
  narrower than you expected, compare it against `GET /api/access` before assuming a bug.
</Note>

## Headers

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

## Response

<ResponseField name="account" type="object">
  <Expandable title="account properties">
    <ResponseField name="user_id" type="string">Your user ID</ResponseField>
    <ResponseField name="email" type="string">Account email</ResponseField>
    <ResponseField name="username" type="string">Account username</ResponseField>
    <ResponseField name="is_enterprise" type="boolean">Whether this is an enterprise account</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="authenticated_via" type="string">
  Always `api_key` — developer API tokens are only issued via API key exchange.
</ResponseField>

<ResponseField name="datasets" type="object">
  Entitlements per dataset. Contains `recently_registered`, which holds one entry each
  for `gst`, `company` and `director`.

  <Expandable title="dataset entitlement properties">
    <ResponseField name="enabled" type="boolean">
      Whether this dataset may be queried at all. When `false`, the matching feed
      endpoint returns `403 NO_DATASET_ACCESS`.
    </ResponseField>

    <ResponseField name="granted_by" type="string | null">
      What grants the access: `subscription`, `offer`, or `enterprise`. `null` when not enabled.
    </ResponseField>

    <ResponseField name="reason" type="string | null">
      Why access is withheld, e.g. `no_active_plan_grants_this_dataset` or
      `unknown_dataset`. `null` when access is granted.
    </ResponseField>

    <ResponseField name="territory" type="object">
      The geographic scope applied to every query for this dataset.

      <Expandable title="territory properties">
        <ResponseField name="restricted" type="boolean">
          `false` means nationwide. `true` means the lists below are enforced.
        </ResponseField>

        <ResponseField name="states" type="array | null">Permitted states</ResponseField>
        <ResponseField name="districts" type="array | null">Permitted districts</ResponseField>
        <ResponseField name="pincodes" type="array | null">Permitted pincodes</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="date_window" type="object | null">
      The registration-date range you may actually query.

      <Expandable title="date_window properties">
        <ResponseField name="from" type="string | null">Earliest queryable date (YYYY-MM-DD)</ResponseField>
        <ResponseField name="to" type="string | null">Latest queryable date (YYYY-MM-DD)</ResponseField>

        <ResponseField name="anchored_to_subscription" type="boolean">
          When `true`, `from` is anchored to your subscription start — you cannot query
          registrations from before you subscribed.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="plans" type="array">
      The plans granting this dataset.

      <Expandable title="plan properties">
        <ResponseField name="plan_name" type="string">Plan or offer name</ResponseField>
        <ResponseField name="interval" type="string">Billing interval</ResponseField>
        <ResponseField name="granted_by" type="string">`subscription`, `offer`, or `enterprise`</ResponseField>
        <ResponseField name="expires_at" type="string | null">Expiry timestamp</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="credits" type="array">
  Credit balances on the account, each with `type`, `balance`, `total_credits`,
  `used_credits` and `last_updated`.
</ResponseField>

<ResponseField name="rate_limits" type="object">
  Current rate limit consumption, including `detail_endpoints` with `used_today`,
  `daily_limit` and `remaining`.
</ResponseField>

<ResponseField name="generated_at" type="string">
  When this snapshot was produced (UTC).
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET https://api.finscreener.in/api/access \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

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

  response = requests.get(
      "https://api.finscreener.in/api/access",
      headers={"Authorization": f"Bearer {token}"}
  )
  access = response.json()

  gst = access["datasets"]["recently_registered"]["gst"]
  if gst["enabled"]:
      print("Queryable from", gst["date_window"]["from"], "to", gst["date_window"]["to"])
      if gst["territory"]["restricted"]:
          print("Limited to states:", gst["territory"]["states"])
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "account": {
      "user_id": "usr_8f21c0",
      "email": "dev@example.com",
      "username": "example-dev",
      "is_enterprise": false
    },
    "authenticated_via": "api_key",
    "datasets": {
      "recently_registered": {
        "gst": {
          "enabled": true,
          "granted_by": "subscription",
          "reason": null,
          "territory": {
            "restricted": true,
            "states": ["Karnataka", "Maharashtra"],
            "districts": null,
            "pincodes": null
          },
          "date_window": {
            "from": "2026-07-07",
            "to": "2026-07-18",
            "anchored_to_subscription": true
          },
          "plans": [
            {
              "plan_name": "New GST - Karnataka",
              "interval": "monthly",
              "granted_by": "subscription",
              "expires_at": "2026-08-07T00:00:00Z"
            }
          ]
        },
        "company": {
          "enabled": false,
          "granted_by": null,
          "reason": "no_active_plan_grants_this_dataset",
          "territory": {
            "restricted": false,
            "states": null,
            "districts": null,
            "pincodes": null
          },
          "date_window": null,
          "plans": []
        },
        "director": {
          "enabled": false,
          "granted_by": null,
          "reason": "no_active_plan_grants_this_dataset",
          "territory": {
            "restricted": false,
            "states": null,
            "districts": null,
            "pincodes": null
          },
          "date_window": null,
          "plans": []
        }
      }
    },
    "credits": [
      {
        "type": "gst_contact",
        "balance": 250,
        "total_credits": 500,
        "used_credits": 250,
        "last_updated": "2026-07-18T09:14:00Z"
      }
    ],
    "rate_limits": {
      "detail_endpoints": {
        "used_today": 42,
        "daily_limit": 100,
        "remaining": 58
      },
      "date": "2026-07-18"
    },
    "generated_at": "2026-07-18T11:02:31Z"
  }
  ```
</ResponseExample>