PATCH /v1/scheduled-reports/{scheduled_report_id}

Update a scheduled report

scope write:scheduled cost 1 RU idempotent optional

Partial update of a scheduled report. Mutable fields: name, frequency, is_active, next_run_at, and the client delivery fields (deliver_to_client, recipient_emails, cc_self, client_intro_message, template_key, account_template_id, require_review).

Note: changing frequency does not recompute next_run_at; set both explicitly if you want the new cadence to take effect from a specific moment.

Path parameters

scheduled_report_id string required

Scheduled report UUID.

Query parameters

dry_run boolean optional

Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns 200 with a dry_run object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns 422.

default: false

Header parameters

Idempotency-Key string optional

Optional. A retry with the same key and body within 24 hours replays the first response.

Request body

application/json required

Type: ScheduledReportUpdate

account_template_id string (nullable) nullable

One of the account's own report templates, used instead of a house template. Pass an empty string to clear it.
cc_self boolean (nullable) nullable

Copy the schedule owner on every client report.
client_intro_message string (nullable) nullable

A short note that opens the client report email.
deliver_to_client boolean (nullable) nullable

Email a branded report to the client after every completed run: a PDF built from the schedule's template, sent from the agency's sending domain to recipient_emails plus the brand's client email. Needs the brand owner on Agency (a paid plan, not a trial); asking for it below that answers 403 brand_plan_required.
frequency enum (nullable) nullable

New cadence. Pass next_run_at alongside to realign the next tick.
is_active boolean (nullable) nullable

Set to false to pause; true to resume.
name string (nullable) nullable
next_run_at string (nullable) nullable

Override the next execution time (ISO-8601 UTC, include Z or offset).
recipient_emails array of string (nullable) nullable

Extra recipients of the client report (up to 10), on top of the brand's client email.
require_review boolean (nullable) nullable

When true (the default for new schedules) the composed report waits for someone to approve and send it in the app. Set false to have it sent automatically when the run completes.
template_key string (nullable) nullable

House report template the run is composed from. Pass an empty string to clear it and fall back to the account's default template.

Example payload

{
  "is_active": false,
  "name": "adidas weekly visibility (renamed)"
}

Responses

Updated a scheduled report application/json

Type: ScheduledReport

brand_id string required

Owning brand id (UUID).
created_at string required

ISO-8601 timestamp when the schedule was created.

format: `date-time`
frequency enum required

Cadence the schedule runs at.
id string required

Stable schedule identifier (UUID).
is_active boolean required

Whether the schedule will run on its next tick.
name string required

Human-readable label.
account_template_id string (nullable) nullable

One of the account's own report templates, used instead of a house template. Pass an empty string to clear it.
cc_self boolean

Copy the schedule owner on every client report.

default: `false`
client_intro_message string (nullable) nullable

A short note that opens the client report email.
deliver_to_client boolean

Email a branded report to the client after every completed run: a PDF built from the schedule's template, sent from the agency's sending domain to recipient_emails plus the brand's client email. Needs the brand owner on Agency (a paid plan, not a trial); asking for it below that answers 403 brand_plan_required.

default: `false`
last_delivered_at string (nullable) nullable

When the last client report was sent or attempted.

format: `date-time`
last_delivery_status string (nullable) nullable

Outcome of the last client delivery, e.g. sent 2/3 or skipped: no recipients.
last_error_message string (nullable) nullable

Human-readable failure reason from the last run, when applicable.
last_run_at string (nullable) nullable

ISO-8601 timestamp of the last execution.

format: `date-time`
last_run_status enum (nullable) nullable

Outcome of the last execution.
next_run_at string (nullable) nullable

ISO-8601 timestamp of the next scheduled execution.

format: `date-time`
object string

Always scheduled_report.

default: `scheduled_report`
recipient_emails array of string

Extra recipients of the client report (up to 10), on top of the brand's client email.
require_review boolean

When true (the default for new schedules) the composed report waits for someone to approve and send it in the app. Set false to have it sent automatically when the run completes.

default: `true`
template_key string (nullable) nullable

House report template the run is composed from. Pass an empty string to clear it and fall back to the account's default template.

Example response

{
  "brand_id": "3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04",
  "cc_self": false,
  "created_at": "2026-03-01T10:00:00+00:00",
  "deliver_to_client": true,
  "frequency": "weekly",
  "id": "018e7c2d-33ab-7df1-b1cd-2ac3a8f9112d",
  "is_active": true,
  "last_delivered_at": "2026-04-01T09:04:40+00:00",
  "last_delivery_status": "sent 1/1",
  "last_run_at": "2026-04-01T09:00:11.412+00:00",
  "last_run_status": "completed",
  "name": "adidas weekly visibility",
  "next_run_at": "2026-04-08T09:00:00+00:00",
  "object": "scheduled_report",
  "recipient_emails": [
    "marketing@e2e.test"
  ],
  "require_review": false
}

Request validation failed application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Missing or invalid credentials application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid credentials"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

You do not have permission to access this resource application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "forbidden",
    "message": "You do not have permission to access this resource"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Resource not found application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Resource conflict application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "conflict",
    "message": "Resource conflict"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Request body did not match the expected schema application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "body_validation_error",
    "message": "Request body did not match the expected schema"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Per-minute rate limit exceeded application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Per-minute rate limit exceeded"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

An unexpected error occurred application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Service temporarily unavailable, please retry application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "service_unavailable",
    "message": "Service temporarily unavailable, please retry"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Request example

curl --request PATCH \
  --url 'https://api.rankprompt.com/v1/scheduled-reports/your_scheduled_report_id_here?dry_run=false' \
  --header 'Authorization: Bearer rp_live_<YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "is_active": false,
  "name": "adidas weekly visibility (renamed)"
}'

const fetch = require('node-fetch');

const url = 'https://api.rankprompt.com/v1/scheduled-reports/your_scheduled_report_id_here?dry_run=false';
const options = {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer rp_live_<YOUR_API_KEY>',
    'Content-Type': 'application/json'
  },
  body: '{"is_active":false,"name":"adidas weekly visibility (renamed)"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

import requests

url = "https://api.rankprompt.com/v1/scheduled-reports/your_scheduled_report_id_here"

querystring = {"dry_run":"false"}

payload = {
    "is_active": False,
    "name": "adidas weekly visibility (renamed)"
}
headers = {
    "Authorization": "Bearer rp_live_<YOUR_API_KEY>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers, params=querystring)

print(response.json())