# Listening Topic Backfills API V3 — Developer Guide

- **Applies to:** Sprinklr Listening Topic Backfills API V3 (`GET /api/v3/listening/backfill`)


## 1. Overview

Use the Listening Topic Backfills API to retrieve details of previously created Listening Topic backfill jobs. The response can include the associated Topic ID, backfill time range, selected sources, status, initiating user, and available estimate fields.

### 1.1 Supported operation

| Operation | Method | Path |
|  --- | --- | --- |
| Fetch one or more Listening Topic backfills | `GET` | `/api/v3/listening/backfill` |


### 1.2 Retrieval model

The `id` query parameter accepts one backfill ID or a comma-separated list of backfill IDs.

| Mode | Request | Result |
|  --- | --- | --- |
| Single backfill | `GET /api/v3/listening/backfill?id={id}` | Returns the matching backfill in `data[]`. |
| Multiple backfills | `GET /api/v3/listening/backfill?id={id1},{id2}` | Returns all matched backfills in `data[]`. |
| Mixed valid and invalid IDs | Supply valid, blank, invalid, or unavailable IDs together | Returns matched records in `data[]` and item-level failures in `errors[]`. |


### 1.3 Common use cases

- Monitor a previously created backfill job.
- Review the Topic and time range associated with a backfill.
- Verify selected source channels.
- Check the current backfill status.
- Review source-level and total estimated record counts when returned.
- Audit which user initiated a backfill.


## 2. Base URL and environment

Use the environment-specific API V3 base URL:

```text
https://api3.sprinklr.com/{env}/api/v3
```

The Backfills resource is:

```text
https://api3.sprinklr.com/{env}/api/v3/listening/backfill
```

Replace `{env}` with the assigned environment identifier.

## 3. Authentication and common headers

| Header | Value | Required | Description |
|  --- | --- | --- | --- |
| `Authorization` | `Bearer {{accessToken}}` | Yes | OAuth access token used to authenticate the request. |
| `Key` | `{{apiKey}}` | Yes | API key used to authenticate the application. |
| `Accept` | `application/json` | Recommended | Specifies the expected response format. |


Do not publish access tokens, API keys, or session cookies in examples.

## 4. Fetch Listening Topic Backfills

```http
GET /api/v3/listening/backfill
```

Retrieves one or more Listening Topic backfill jobs by ID.

### 4.1 Query parameters

| Parameter | Sub-parameter | Location | Required | Type | Description |
|  --- | --- | --- | --- | --- | --- |
| `id` | N/A | Query | Yes | String | Backfill ID or comma-separated list of Listening Backfill job IDs. A maximum of 50 identifiers can be provided in one request. |


> The working examples use `id` as a query parameter. The source document also shows a path-style endpoint, but its cURL examples consistently use `/listening/backfill?id={id}`.


### 4.2 Fetch a single backfill

#### Example request

```bash
curl --location 'https://api3.sprinklr.com/{env}/api/v3/listening/backfill?id=6995b29cd7890350f0da3bb1' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Key: {{apiKey}}'
```

#### Example response

```json
{
  "data": [
    {
      "id": "6995b29cd7890350f0da3bb1",
      "topicId": "6982f494a1ecaf1e779b323e",
      "fromTimeEpochMillis": 1771266600000,
      "toTimeEpochMillis": 1771353000000,
      "sources": [
        "REVIEWS"
      ],
      "userId": 66006626,
      "status": "Estimate Failed"
    }
  ],
  "errors": []
}
```

### 4.3 Fetch multiple backfills

Provide multiple IDs as a comma-separated list. Commas may be URL-encoded as `%2C`.

#### Example request

```bash
curl --location --globoff 'https://api3.sprinklr.com/{env}/api/v3/listening/backfill?id=6995b29cd7890350f0da3bb1%2C6995b318d7890350f0dab105' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Key: {{apiKey}}'
```

#### Example response

```json
{
  "data": [
    {
      "id": "6995b29cd7890350f0da3bb1",
      "topicId": "6982f494a1ecaf1e779b323e",
      "fromTimeEpochMillis": 1771266600000,
      "toTimeEpochMillis": 1771353000000,
      "sources": [
        "REVIEWS"
      ],
      "userId": 66006626,
      "status": "Estimate Failed"
    },
    {
      "id": "6995b318d7890350f0dab105",
      "topicId": "6735e5d2016ea76ec795b860",
      "fromTimeEpochMillis": 1771180200000,
      "toTimeEpochMillis": 1771353000000,
      "sources": [
        "FACEBOOK"
      ],
      "estimatedSourceVsCount": {
        "FACEBOOK": 0
      },
      "userId": 66006626,
      "status": "Backfill Completed",
      "estimatedDataCount": 0
    }
  ],
  "errors": []
}
```

### 4.4 Partial success with valid, blank, invalid, and unavailable IDs

A multi-ID request may return successfully retrieved jobs in `data[]` and item-level failures in `errors[]`.

#### Example request

```bash
curl --location --globoff 'https://api3.sprinklr.com/{env}/api/v3/listening/backfill?id=6995b29cd7890350f0da3bb1%2C6995b318d7890350f0dab105%2C%2CInvalid%2Cabcd' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Key: {{apiKey}}'
```

#### Example response

```json
{
  "data": [
    {
      "id": "6995b29cd7890350f0da3bb1",
      "topicId": "6982f494a1ecaf1e779b323e",
      "fromTimeEpochMillis": 1771266600000,
      "toTimeEpochMillis": 1771353000000,
      "sources": [
        "REVIEWS"
      ],
      "userId": 66006626,
      "status": "Estimate Failed"
    },
    {
      "id": "6995b318d7890350f0dab105",
      "topicId": "6735e5d2016ea76ec795b860",
      "fromTimeEpochMillis": 1771180200000,
      "toTimeEpochMillis": 1771353000000,
      "sources": [
        "FACEBOOK"
      ],
      "estimatedSourceVsCount": {
        "FACEBOOK": 0
      },
      "userId": 66006626,
      "status": "Backfill Completed",
      "estimatedDataCount": 0
    }
  ],
  "errors": [
    {
      "id": "6995b349f58d8b601be9ed6c",
      "code": 400,
      "message": "Invalid id format: ''. Value cannot be empty or blank."
    },
    {
      "id": "6995b349f58d8b601be9ed6d",
      "code": 404,
      "message": "Listening_backfill not found for id: 'Invalid'. Verify the listening_backfill exists and you have access permissions."
    },
    {
      "id": "6995b349f58d8b601be9ed6e",
      "code": 404,
      "message": "Listening_backfill not found for id: 'abcd'. Verify the listening_backfill exists and you have access permissions."
    }
  ]
}
```

Always inspect `errors[]`, even if `data[]` contains records.

### 4.5 Maximum ID limit

A maximum of 50 Listening Backfill IDs can be supplied in one request. Split larger lists into batches of 50.

#### Example request exceeding the limit

```bash
curl --location --globoff 'https://api3.sprinklr.com/{env}/api/v3/listening/backfill?id=id1%2Cid2%2Cid3%2Cid4%2Cid5%2Cid6%2Cid7%2Cid8%2Cid9%2Cid10%2Cid11%2Cid12%2Cid13%2Cid14%2Cid15%2Cid16%2Cid17%2Cid18%2Cid19%2Cid20%2Cid21%2Cid22%2Cid23%2Cid24%2Cid25%2Cid26%2Cid27%2Cid28%2Cid29%2Cid30%2Cid31%2Cid32%2Cid33%2Cid34%2Cid35%2Cid36%2Cid37%2Cid38%2Cid39%2Cid40%2Cid41%2Cid42%2Cid43%2Cid44%2Cid45%2Cid46%2Cid47%2Cid48%2Cid49%2Cid50%2Cid51' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Key: {{apiKey}}'
```

#### Example response

```json
{
  "errors": [
    {
      "id": "6995b490f58d8b601be9ed71",
      "code": 400,
      "message": "Maximum of 50 listening_backfill identifiers supported per request. Provided: 51. Consider splitting you request in batches of 50 identifiers per request"
    }
  ]
}
```

## 5. Response Parameters

| Parameter | Sub-parameter | Type | Description |
|  --- | --- | --- | --- |
| `data` | N/A | Array | Listening Backfill jobs successfully retrieved by the API. |
| `data` | `id` | String | Unique identifier of the Listening Backfill job. |
| `data` | `topicId` | String | Unique identifier of the Listening Topic associated with the job. |
| `data` | `fromTimeEpochMillis` | Long | Start time of the backfill period in epoch milliseconds. |
| `data` | `toTimeEpochMillis` | Long | End time of the backfill period in epoch milliseconds. |
| `data` | `sources` | Array | Source channels included in the backfill request. |
| `data.sources` | `sources[]` | String | Individual source channel, for example `REVIEWS` or `FACEBOOK`. |
| `data` | `estimatedSourceVsCount` | Object | Source-level estimated record counts for the backfill job. Returned when available. |
| `data.estimatedSourceVsCount` | `<source_name>` | Long | Estimated count for a specific source channel. |
| `data` | `userId` | Long | Identifier of the user who initiated the backfill. |
| `data` | `status` | String | Current status of the Listening Backfill job. |
| `data` | `estimatedDataCount` | Long | Estimated total number of records available for backfill. Returned when available. |
| `errors` | N/A | Array | Errors encountered while processing the request. Empty on complete success. |
| `errors` | `id` | String | Unique identifier associated with the error record. |
| `errors` | `code` | Integer | Error code returned for the failed item or request. |
| `errors` | `message` | String | Detailed error description. |


## 6. Response Formats

### 6.1 Complete success

```json
{
  "data": [
    {
      "id": "<BACKFILL_ID>"
    }
  ],
  "errors": []
}
```

### 6.2 Partial success

```json
{
  "data": [
    {
      "id": "<VALID_BACKFILL_ID>"
    }
  ],
  "errors": [
    {
      "id": "<ERROR_ID>",
      "code": 404,
      "message": "<ERROR_MESSAGE>"
    }
  ]
}
```

### 6.3 Request-level failure

```json
{
  "errors": [
    {
      "id": "<ERROR_ID>",
      "code": 400,
      "message": "<ERROR_MESSAGE>"
    }
  ]
}
```

## 7. Error Handling

### 7.1 Error object

| Field | Type | Description |
|  --- | --- | --- |
| `id` | String | Unique identifier associated with the error. |
| `code` | Integer | Error code. |
| `message` | String | Description of the failure. |


### 7.2 Documented error scenarios

| Code | Scenario | Description |
|  --- | --- | --- |
| `400` | Blank ID | The `id` list contains an empty value. |
| `400` | Too many IDs | More than 50 Backfill IDs were supplied. |
| `404` | ID not found or unavailable | The Backfill does not exist or the caller does not have access. |


## 8. Status and Estimate Fields

The examples include the following status values:

- `Estimate Failed`
- `Backfill Completed`


When returned, `estimatedSourceVsCount` provides source-level estimates and `estimatedDataCount` provides a total estimated record count.

Do not treat the examples as a complete status enumeration. Validate all supported status values against the service contract before publication.

## 9. Use Cases

### 9.1 Monitor one backfill

Retrieve one job by ID and inspect its current `status`.

### 9.2 Review the configured time range

Use `fromTimeEpochMillis` and `toTimeEpochMillis` to identify the backfill period.

### 9.3 Retrieve bulk job details

Submit up to 50 comma-separated IDs and process the returned `data[]` records.

### 9.4 Handle partial results

Process successful jobs in `data[]` and separately handle item-level failures in `errors[]`.

### 9.5 Review estimates

Inspect `estimatedSourceVsCount` and `estimatedDataCount` when they are present.

## 10. Best Practices

- Persist the Backfill ID when a job is created.
- Send no more than 50 IDs in one request.
- URL-encode comma-separated values when required by the client.
- Always inspect `errors[]` because multi-ID requests can return partial results.
- Treat `estimatedSourceVsCount` and `estimatedDataCount` as optional fields.
- Interpret all backfill time fields as epoch milliseconds.
- Do not include cookies, access tokens, or API keys in published examples.


## 11. Quick Reference

| Task | Request |
|  --- | --- |
| Fetch one Backfill | `GET /api/v3/listening/backfill?id={id}` |
| Fetch multiple Backfills | `GET /api/v3/listening/backfill?id={id1},{id2}` |
| Maximum IDs | 50 per request |
| Success data | `data[]` |
| Item or request failures | `errors[]` |
| Required authentication | `Authorization` and `Key` headers |


*All credentials are placeholders. Example IDs and payloads are retained for documentation purposes and must be validated before publication.*