> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sacra.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Rank companies - Companies API
> Build a ranked list of active companies by valuation, revenue, or total funding.
Use this endpoint to build company leaderboards, screen a market, or monitor the
companies with the highest or lowest financial metrics. Choose `valuation`,
`revenue`, or `total_funding` with `sort_by`, then narrow the results by company
type, sort order, and result limit.
The response includes the company identity, the metric used for ranking, its
numeric value, and the date associated with that value. It also returns metadata
that summarizes the applied ranking options and the total number of companies
with a value for the selected metric. Companies without that metric are not
included in the ranking.
By default, the endpoint returns up to 50 companies ranked by valuation in
descending order. You can request up to 100 results.
For example, use the following query to return the 25 highest-valued private
companies:
```bash theme={null}
curl --request GET \
--url 'https://sacra.com/api/v1/companies/rankings/?sort_by=valuation&company_type=private&order=desc&limit=25' \
--header 'Authorization: Token YOUR_API_KEY'
```
## OpenAPI
````yaml openapi.json GET /api/v1/companies/rankings/
openapi: 3.0.3
info:
title: Sacra API
version: 1.0.0
description: >-
The Sacra API currently supports querying News, Documents, Companies and
Categories that enable you to use Sacra research within your own
application.
## **Getting started guide**
To start using the APIs, you need to:
- Only available to **Platforms** and **Funds** tier members. (See
[here](https://sacra.com/pricing/))
- You must use a valid API Key to send requests to the API endpoints. You
can generate your API key in the Api Keys section of your [Organization
Settings](https://sacra.com/orgs/settings/general/).
- The API returns request responses in JSON format. When an API request
returns an error, it is sent in the JSON response as an error key.
## Authentication
The Sacra API uses Tokens for authentication.
You can generate a Sacra API Key/Token in the Api Keys section of your
[Organization Settings](https://sacra.com/orgs/settings/general/).
You must include an API Key/Token in each request to the Sacra API with the
**Authorization** request header.
### Authentication error response
If a Token is missing, malformed, or invalid, you will receive an HTTP 401
Unauthorized response code.
### **Need some help?**
In case you have questions, we will eventually provide tutorials and a FAQ
page. But for now you can check out the
[#developers](https://discord.gg/mTswyV8gg3) channel in our community
[Discord](https://discord.gg/mTswyV8gg3), there’s a good chance our
community has an answer for you.
## Authorization
| **Key** | **Value** |
| --- | --- |
| Authorization | Token {{API_KEY}} |
servers:
- url: https://sacra.com
description: Production
security: []
tags:
- name: Companies
- name: Categories
- name: Events
- name: News
- name: Documents
- name: Filings
- name: Embeds
- name: Metrics
- name: Funding (Legacy)
paths:
/api/v1/companies/rankings/:
get:
tags:
- Companies
summary: Rank Companies
description: >-
Return active companies ranked by a supported company financial metric.
This endpoint is intended for bounded monitoring and research workflows,
not arbitrary sorting.
operationId: companies_rankings
parameters:
- in: query
name: company_type
schema:
type: string
enum:
- all
- private
- public
description: Filter by company type. Defaults to `all`.
- in: query
name: limit
schema:
type: integer
description: Maximum rows to return. Defaults to 50; max 100.
- in: query
name: order
schema:
type: string
enum:
- asc
- desc
description: Sort order. Defaults to `desc`.
- in: query
name: sort_by
schema:
type: string
enum:
- revenue
- total_funding
- valuation
description: Metric to rank by. Defaults to `valuation`.
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyRankingsResponse'
description: Ranked companies for the requested metric.
'400':
content:
text/plain:
schema:
type: string
example: >-
Unsupported sort_by. Supported values: valuation, revenue,
total_funding
description: Invalid query parameter.
security:
- SacraAPIAuthentication: []
components:
schemas:
CompanyRankingsResponse:
type: object
properties:
companies:
type: array
items:
$ref: '#/components/schemas/CompanyRankingItem'
meta:
$ref: '#/components/schemas/CompanyRankingsMeta'
required:
- companies
- meta
CompanyRankingItem:
type: object
properties:
id:
type: integer
slug:
type: string
name:
type: string
domain:
type: string
type:
type: string
description: Either `private` or `public`.
metric:
type: string
description: Ranking metric used for this row.
metric_value:
type: number
format: double
description: Numeric value used for sorting.
metric_date:
type: string
nullable: true
description: Date associated with the metric, if present.
required:
- domain
- id
- metric
- metric_date
- metric_value
- name
- slug
- type
CompanyRankingsMeta:
type: object
properties:
sort_by:
type: string
order:
type: string
company_type:
type: string
limit:
type: integer
total_ranked:
type: integer
required:
- company_type
- limit
- order
- sort_by
- total_ranked
securitySchemes:
SacraAPIAuthentication:
type: apiKey
in: header
name: Authorization
description: |-
Authenticate using one of two formats:
- **Organization/user token:** `Token `
- **Stytch JWT:** `Bearer `
````