Detecting Source Description Changes

The Get Source Description Changes call lets you efficiently determine which source descriptions have changed since a given time. Instead of re-downloading and comparing full source descriptions, send a request containing a batch of source description IDs and a timestamp and receive a list of the source descriptions that have changed since the given timestamp.

When to Use

Use this endpoint when you need to:

• Synchronize a local cache of source descriptions.
• Poll for updates in a monitoring/sync pipeline.
• Reduce bandwidth and work by fetching only changed records.

API Request Details

The Get Source Description Changes call accepts up to 100 source description IDs and a since timestamp. The response returns only the IDs that have changed. For specific details on the request and response format, see the following documentation.

• Example Request: Example request and response including headers, parameters, and bodies.
• API Reference: Path, parameter, header, and body documentation.

Typical Workflow

1. Store the timestamp of your last successful sync.
2. Call Get Source Description Changes with that since timestamp and up to 100 IDs.
3. If the response includes IDs, call Read Source Description for those IDs to retrieve full, current objects.
4. Update your local cache, then record a new sync timestamp for the next cycle.

Best Practices

• Batching: If you have more than 100 IDs, split them into multiple requests.
• Timestamps: Use a Unix epoch timestamp in milliseconds for the since parameter.
• Selective fetch: Only fetch full source descriptions for the IDs returned by this endpoint.
• Resilience: Handle empty results (no changes) gracefully and continue using your existing cache.

Error Handling

• 204 No Content: None of the provided IDs have changed since the given timestamp.
• 400 Bad Request: Missing/invalid since or request body shape; too many IDs (>100).
• 401 Unauthorized: Missing or expired access token.
• 429 Too Many Requests: Back off and retry per response headers.
• 5XX Server Errors: Temporary issues; implement retries with exponential backoff.

📘

Notes:

Unknown or invalid IDs are ignored by the service and simply do not appear in the changed set. A Warning header may contain information about IDs that were not found.

Always validate your input and keep batches ≤ 100.