# List opportunities (https://terac.com/docs/developers/reference/listOpportunities)

`GET https://terac.com/api/external/v2/opportunities`

Lists your organization's opportunities, newest first, with each one's status, target and pricing. Filter by `projectId` or by one `status`. Returns up to `limit` per page; while `pagination.has_more` is true, pass `pagination.next_cursor` back as `cursor` for the next page. Deleted opportunities are left out. `pricing` is what launching charged, so it is null on a draft; read a draft's estimate from `GET /opportunities/{opportunityId}`.

## Authorization

Requires a Bearer token via the `Authorization` header.

```
Authorization: Bearer <token>
```

## Query Parameters

- `limit` (integer): Most items to return in one page, from 1 to 100. Defaults to 25.
- `cursor` (string): `pagination.next_cursor` from the previous page, to fetch the page after it. Omit it for the first page.
- `status` (string): Return only opportunities in this status: `draft`, `active`, `fulfilled`, `paused`, `stopped` or `completed`. `draft` includes opportunities Terac is still preparing.
- `projectId` (string): Return only opportunities filed under this project ID.

## Responses

### 200: One page of opportunity summaries.

- `data` (array) **(required)**
  - `id` (string) **(required)**
  - `title` (string) **(required)**
  - `status` (string) **(required)**: one of: `draft`, `active`, `fulfilled`, `paused`, `stopped`, `completed`
  - `num_participants` (integer) **(required)**
  - `pricing` (object, nullable) **(required)**
    - `cost_per_participant_cents` (integer) **(required)**
    - `total_cost_cents` (integer) **(required)**
    - `currency` (string) **(required)**: one of: `usd`
  - `created_at` (string) **(required)**
  - `dashboard_url` (string, nullable) **(required)**: The study's own page. It routes itself by status: an editable draft opens the builder, anything else opens submissions. Never null. Give this when you do not know which tab the customer needs; when `draft_editor` is set, prefer that instead, since it opens the same builder the customer would review in. Null if Terac cannot resolve the organization or project this link belongs to.
- `pagination` (object) **(required)**
  - `next_cursor` (string, nullable) **(required)**
  - `has_more` (boolean) **(required)**
### 400: Invalid input data

- `message` (string) **(required)**: The error message
- `code` (string) **(required)**: The error code
- `issues` (array): An array of issues that were responsible for the error
  - `message` (string) **(required)**
### 401: The API key is missing, invalid, disabled, expired or revoked, its owner no longer exists, or it is not linked to an organization. The body is nested under `error`.

- `error` (object) **(required)**
  - `code` (string) **(required)**: one of: `UNAUTHORIZED`: The error code.
  - `message` (string) **(required)**: What went wrong.
### 403: Either the account that owns the API key is banned or deleted (from the key check, nested under `error`), or the key's owner lacks the organization permission this operation needs (from the operation, with `code` and `message` at the top level).

- One of: API key error (403)
  - `error` (object) **(required)**
    - `code` (string) **(required)**: one of: `FORBIDDEN`: The error code.
    - `message` (string) **(required)**: What went wrong.
- One of: Insufficient access error (403)
  - `message` (string) **(required)**: The error message
  - `code` (string) **(required)**: The error code
  - `issues` (array): An array of issues that were responsible for the error
    - `message` (string) **(required)**
### 404: Not found

- `message` (string) **(required)**: The error message
- `code` (string) **(required)**: The error code
- `issues` (array): An array of issues that were responsible for the error
  - `message` (string) **(required)**
### 429: The API key is rate limited. A key accepts 100 requests, then refuses every request until more than 60 seconds pass with no accepted request; refused requests do not extend the wait. Wait the number of seconds in `Retry-After`, then retry. The body is nested under `error`.

- `error` (object) **(required)**
  - `code` (string) **(required)**: one of: `RATE_LIMITED`: The error code.
  - `message` (string) **(required)**: What went wrong.
### 500: Internal server error

- `message` (string) **(required)**: The error message
- `code` (string) **(required)**: The error code
- `issues` (array): An array of issues that were responsible for the error
  - `message` (string) **(required)**