# Profiles API


You can use the Profiles API to programmatically run your Profiles project and check its run status.

## Prerequisites

- Set up a Profiles project in the [RudderStack dashboard](https://app.rudderstack.com/). Then, note down the Profiles project ID from the URL:

{{< image src="images/api/source-id.webp" alt="Profiles project ID from the URL" >}}

- Generate a [workspace-level Service Access Token]({{< ref "access-management/service-access-tokens.md#workspace-sat" >}}) in the RudderStack dashboard with the following [permissions]({{< ref "access-management/policies-overview.md#resource-permissions" >}}) to authenticate the API:

| Resource | Permissions |
| :----| :-----|
| Profiles | **Edit** |

#### Token permissions for legacy RBAC system

If you are on the [legacy Permissions Management (RBAC) system]({{< ref "archive/dashboard-guides/user-management.md" >}}), your workspace-level Service Access Token should have minimum **Editor** permissions.

See [this documentation]({{< ref "archive/dashboard-guides/service-access-tokens.md#generate-service-access-token" >}}) for more information on generating the token.

{{< image src="images/access-management/permissions/legacy/editor.webp" alt="workspace-level Service Access Token with Editor permission" >}}

## Authentication

The Profiles API uses [Bearer authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/) in the following format:

```
Authorization: Bearer <SERVICE_ACCESS_TOKEN>
```

## Base URL

Use the base URL for your API requests depending on your region:

{{< tabs tabTotal="2" >}}
{{% tab tabName="Standard" %}}
```text
https://api.rudderstack.com/v2
```
{{% /tab %}}
{{% tab tabName="EU-Standard" %}}
```text
https://api.eu.rudderstack.com/v2
```
{{% /tab %}}
{{< /tabs >}}

## Run project

You can trigger the run of a Profiles project using the below endpoint:

{{% api-method method="post" host="https://api.rudderstack.com/v2" path="/sources/<profilesID>/start" %}}

{{< info >}}
When you trigger a run through this API endpoint, RudderStack always fetches the latest code from your connected Git repository. You don't need to use the **Fetch latest** button in the dashboard before triggering an API run.

The **Fetch latest** button on the **Settings** page of your Profiles project only applies to the RudderStack dashboard. RudderStack caches the project details (like the number of features) to power the UI. If you have recently pushed changes to your Git repository and want to see them reflected in the dashboard immediately, use this setting to refresh the cache.

{{< figure src="images/profiles/fetch-latest-setting.webp" alt="Fetch latest button" >}}
{{< /info >}}

**Path parameters**

{{< query-params keyname="profilesID" valuename="ID of the Profiles project for which you want to trigger a run." keytype="Required" datatype="String" >}}
<hr/>

**Request body**

{{< query-paramsList >}}
  {{< query-params keyname="parameters" valuename="Specify the parameters and their associated values to be passed for running the project. Multiple parameters can be passed. Each parameter and its associated value is a single string. Allowed parameters: <br /><br /><ul><li>`--model_refs`</li><li>`--begin_time`</li><li>`--end_time`</li><li>`--rebase_incremental`</li></li></ul>" keytype="Optional" datatype="Array" >}}
{{< /query-paramsList >}}

**Example request**

{{< tabs tabTotal="2" >}}
{{% tab tabName="HTTP" %}}
```http
POST /v2/sources/<profilesID>/start HTTP/1.1
Host: api.rudderstack.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>

{
  "parameters": ["--model_refs models/id_graph_users"]
}
```
{{% /tab %}}
{{% tab tabName="CURL" %}}
```bash
curl --location 'https://api.rudderstack.com/v2/sources/<profilesID>/start' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
  "parameters": ["--model_refs models/id_graph_users"]
}'
```
{{% /tab %}}
{{< /tabs >}}

**Example response**

```json
{
  "runId": "<run_id>"
}
```

**Response codes**

| Code | Description |
| :----| :---|
| 200 | Run started for the Profiles project. RudderStack also returns a run ID for the project. | 
| 409 | Profiles project is already running for the specified source ID. |

## Get run status

You can get the run status of your Profiles project using the below endpoint:

{{% api-method method="get" host="https://api.rudderstack.com/v2" path="/sources/{profilesID}/runs/{runId}/status" %}}

**Path parameters**

{{< query-params keyname="profilesID" valuename="ID of the Profiles project for which you want to trigger a run." keytype="Required" datatype="String" >}}
{{< query-params keyname="runId" valuename="ID of the Profiles project's run." keytype="Required" datatype="String" >}}

{{< info >}}
You can obtain the `runId` as the response of the [above API endpoint](#run-project) (`/sources/<profilesID>/start`).
{{< /info >}}

**Example request**

{{< tabs tabTotal="2" >}}
{{% tab tabName="HTTP" %}}
```http
GET /v2/sources/<profilesID>/runs/{run_id}/status HTTP/1.1
Host: api.rudderstack.com
Accept: application/json
Authorization: Bearer <token>
```
{{% /tab %}}
{{% tab tabName="CURL" %}}
```bash
curl --location 'https://api.rudderstack.com/v2/sources/<profilesID>/runs/<run_id>/status' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>'
```
{{% /tab %}}
{{< /tabs >}}

**Example response**

```json
{
  "jobId": "string",
  "jobRunId": "string",
  "status": "running",
  "startedAt": "2024-05-31T06:48:08.228Z",
  "finishedAt": "2024-05-31T06:48:08.228Z",
  "tasks": [{
    "taskId": "string",
    "taskRunId": "string",
    "startedAt": "2024-05-31T06:48:08.228Z",
    "finishedAt": "2024-05-31T06:48:08.228Z"
  }]
}
```

**Response parameters**

| Parameter | Type | Description |
| :----|  :---| :---|
| `status` | String | Current status of the run. Valid values are `running` and `finished`. |
| `error` | String | Present only when the run finishes with errors. Contains the error details. |

**Response codes**

| Code | Description |
| :----|  :---|
| 200 | Successfully retrieved the run status of the project. |