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

# Get a rating program

> Find an executable rating program for a market product, check access, and choose a published version to run or download.

A rating program is an executable implementation of the rating plan associated with a market
product and writing company. Market Directory programs have published versions with their own
dates, scope, and limitations.

Rating programs and [product research data](/guides/get-product-data) are separate paid offerings.
Contact [sales@effectiveailabs.com](mailto:sales@effectiveailabs.com) for pricing and program access.
Effective's synthetic example programs are available for learning.

Use an [Effective API key](/getting-started/authentication). Discovery requests read data;
subscribing changes access state for your organization.

## Find a program

Search the Market Directory's rating programs:

```bash theme={null}
curl --request GET \
  --url "https://api.canary.effectiveai.app/api/v2/insurance/rating-programs?name=example-ca-ppa&limit=1" \
  --header "Authorization: Bearer $EFFECTIVE_API_KEY"
```

The response contains `programs` and `nextCursor`. Save a returned program's `id`.
Each program includes its associated product, carrier, and state, where recorded, along with
`access` and `subscription`.

For a market product, filter by its `productId`. You can also filter by `carrierId`, `state`, or
`subscribed=true`. A state filter matches explicit associations; an omitted state does not
establish nationwide applicability. See [List rating programs](/api-reference/rating-programs/list-rating-programs).

## Check access and subscription

[Get a rating program](/api-reference/rating-programs/get-a-rating-program) returns its
documentation and current access:

* `access.canRun` and `access.canDownload` say whether you can run or download it.
* `subscription.subscribed` says whether your organization has an active subscription.
* `subscription.canSubscribe` and `subscription.canUnsubscribe` identify available subscription actions.

Check these fields separately. A subscription preserves existing permission limits, expiration,
and revocation; it does not override them.

When `canSubscribe` is true, [subscribe to the program](/api-reference/rating-programs/subscribe-to-a-rating-program)
with `PUT /insurance/rating-programs/{id}/subscription`, using the returned ID and no request body.
This changes the current organization's subscription across all published and future versions.
It requires a writable user key with `raters:manage` and permission to run or download programs.
The subscription operation is not a payment checkout.

## Choose a published version

[List program versions](/api-reference/rating-programs/list-program-versions) for the returned
program ID. Read the version's effective date, supported dates, scope notes, and release notes
before using it for a risk. Association with a product or state alone does not establish applicability.

Published versions are immutable. Retain the program ID and selected version with your analysis.
If there are no published versions, the program is not ready to subscribe to or download.

## Run or download

For local pricing work, [install Relativities](/relativities/setup), then
[load a program](/relativities/how-to/load-a-program) or
[download a program](/relativities/how-to/download-a-program).
Pin the selected version with `revision=`.

An HTTP client can [download a program version](/api-reference/rating-programs/download-a-program-version).
Choose `kind=program` for a Relativities package or `kind=engine` for the rating engine.
The default is `engine`; a version can lack a program package.

For hosted rating, inspect the version's
[input and output contract](/api-reference/rating-programs/get-a-program’s-input-and-output-schemas)
and [rate with that version](/api-reference/rating-programs/rate-a-submission).
Hosted rating sends the supplied inputs to Effective; Relativities runs downloaded programs locally.

## Recover from access errors

A `403` means the required program access or user permission is missing. Check the program's access
and subscription fields before retrying. A `404` can mean the program, version, or requested package
is unavailable.

[Unsubscribing](/api-reference/rating-programs/unsubscribe-from-a-rating-program) ends the subscription
for the organization. Downloaded files and historical results remain; future downloads normally
require an active subscription. Effective example programs are exempt from that requirement.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.